DID Working Group
The practicalities of the self-publishing process for Working Drafts
This guide is only valid for the publication of regular Working Drafts. Ie, not for FPWD, nor for Candidate Recommendations and beyond.
Publishing the group’s Working Drafts is done via a combination of GitHub and a W3C tool called Echidna. The high-level points to remember are described below. (All the examples use the did-spec
repository as an example, the other repositories are set up in a similar fashion.)
- There is a top-level folder called
snapshot
in the repository. This folder contains the document to be published. This folder contains the final document as generated fromrespec
, plus the dependencies like css files and/or images. - There is a separate branch in the repository called
publish_wd
. - Every time the
master
branch is merged intopublish_wd
(and pushed to the repository) the document is picked up from thesnapshot
, and is automatically published on the W3C site as the “latest version” of the official Working Draft.
What this means in practice is that the group can publish a Working Draft as often as its desires without any human intervention from the W3C staff.
The details of the process are below.
- Prepare the
respec
source - Generate the final version of the document
- Modify (if necessary) the Echidna manifest
- Check the document
- Merge the
master
branch into thepublish_wd
branch
Prepare the respec
source
The respecConfig
content must be adapted. Most of these are to be set only once.
- The data of each editor must include the
w3cid
field, identifying the person in the W3C database. This number appears on the page of the person’s profile page at W3C; alternatively, the staff contact can find it. - Update the value of
previousPublishDate
inrespecConfig
every time a publication happens. The value ofpreviousMaturity
should be kept onWD
.
Generate the final version of the document
The value of specStatus
should not be changed in the source; it should remain ED
. Instead, when viewing the editor’s draft, use the following URL (or its local equivalent if you use a local server): https://w3c.github.io/did-spec/?specStatus=WD&publishDate=2018-07-01 (setting the publication date as appropriate). Using this URL overwrites the values defined in respecConfig
and the result is the right Working Draft format. Use then the standard respec
mechanism to generate the final HTML to be put into snapshot
folder.
Modify (if necessary) the Echidna manifest
There is a top level file called ECHIDNA in the snapshot folder. This contains a list of files to be included in the final publication. This file must be modified if new dependences have been added since the last publication.
Check the document
It is required to run the document through the W3C pubrules’ checker and recommended to run it through the W3C link checker. For both cases, the URL to the snapshot folder’s content should be used: https://w3c.github.io/wpub/snapshot.
Note that, if the ECHIDNA file is incomplete (i.e., some resources are not listed), the link checker will be successful and, nevertheless, the final publication may miss some links (the relevant resource is not copied to the target directory on the W3C server). You should always check whether the content of ECHIDNA is correct (or, alternatively, run the link checker once in a while on the published document rather than the snapshot).
Merge the master
branch into the publish_wd
branch
You should probably do this on your local machine, using your preferred GitHub interface. Commit the changes onto GitHub.
You are done; the new version should appear as https://www.w3.org/TR/did-spec/. It is worth checking the public-tr-notifications
mailing list archive to see if everything is o.k.; successful publications or errors are sent to that list.