Moving the new publication process

Hi Mark and WG participants,

The new publication process allows us to publish the specification to 
/TR/ space (http://www.w3.org/TR/presentation-api in our case) on a 
continuous basis, typically after each new commit or whenever we feel 
like it.

Publication becomes a matter of sending the right command to an online 
service called Echidna, giving it the URL of the document to publish. 
Echidna takes care of checking the document against the publication 
rules (pubrules) and of publishing the spec in /TR/ space.

To automate the publication, the easiest way is to use a continuous 
integration tool on the GitHub repo (Travis CI comes to mind) and have 
it send the command to Echidna after each push to the gh-pages branch or 
when a new tag is created.

The tricky part is passing pubrules. In particular, the "index.html" 
file that we have in our repository right now cannot be used directly, 
because:

1. It says it is an "Editor's Draft" (and links to the ED stylesheet) 
whereas pubrules requires a "Working Draft" (and the WD stylesheet). We 
may change that pretty easily but note that the version on the GitHub 
repo would then be a "Working Draft", not an "Editor's Draft".

2. It does not have the right "This version" and "Previous version" 
links. Adding them manually would not work well with automation since 
these links need to change for each new version by definition, but we 
can certainly update the Makefile to compute the new links whenever a 
new index.html file is generated. This will require fetching the latest 
published version in /TR/ space to extract the right URL, unfortunately, 
but that's easily doable with the right pair of batch commands. I'll 
prepare something.

3. There are a few other editorial hiccups with the current file, but 
they can all be solved once and for all, I'll send the appropriate pull 
requests.

I'm wondering how you would prefer to handle the publication, as editor. 
The alternatives I see are:

a) Full automation: the spec is published whenever we push onto 
gh-pages. That means that "index.html" in the root folder of the GitHub 
repo will have to be a "Working Draft".

b) Full automation with releases: the spec is published whenever we push 
onto gh-pages but the Makefile is updated to also generate a 
"releases/WD.html" spec, that will be the Working Draft to publish.

c) Semi-automated publication: you issue the right command on your local 
computer from time to time to generate the right spec, push it to the 
"releases" folder. We configure Travis CI to detect the push to the 
"releases" folder and automatically send the publication request to Echidna.

I like the ability to distinguish quickly between the Editor's draft in 
the GitHub repo and the Working Draft published in /TR/ space, but I 
also like to keep commits as simple as possible (the fact that 
index.html is updated each time already bugs me ;)) and would prefer to 
automate things as much as possible, not to have to worry about that 
publication process at all.

In the end, I prefer a). There used to be a need to separate Editor's 
Drafts and Working Drafts, but if both documents are kept in sync in the 
end, who cares whether the one on GitHub is called "Editor's Draft" or 
"Working Draft"?

Mark, what would you prefer?
All, any other take on this?

FWIW, other groups that have started to use Echidna do not really have 
this problem because they are using ReSpec as editing tool. ReSpec 
generates the spec on the fly and Echidna knows how to process specs 
edited with ReSpec. Anolis is not integrated yet. A good example of a 
spec that uses ReSpec and Echidna would be:

  https://github.com/w3c/manifest
  (note the ECHIDNA and .travis.yml files in particular)

Also, to learn more about Echidna:

  https://github.com/w3c/echidna/wiki

Thanks,
Francois.

Received on Tuesday, 9 June 2015 10:48:29 UTC