JSON-LD 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
json-ld-syntax repository as an example, the other repositories are set up in a similar fashion.)
- There is a top-level folder called
snapshotin the repository. This folder contains the document to be published. This folder contains the final document as generated from
respec, plus the dependencies like css files and/or images.
- There is a separate branch in the repository called
- Every time the
masterbranch is merged into
publish_wd(and pushed to the repository) the document is picked up from the
snapshot, 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
- Generate the final version of the document
- Modify (if necessary) the Echidna manifest
- Check the document
- Merge the
masterbranch into the
respecConfig content must be adapted. Most of these are to be set only once.
- The data of each editor must include the
w3cidfield, 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
respecConfigevery time a publication happens. The value of
previousMaturityshould be kept on
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/json-ld-syntax/?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
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).
master branch into the
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/json-ld-syntax/. 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.