W3C home > Mailing lists > Public > public-secondscreen@w3.org > June 2015

Re: Moving the new publication process

From: Mark Watson <watsonm@netflix.com>
Date: Tue, 9 Jun 2015 07:09:38 -0700
Message-ID: <-2364344904638704599@unknownmsgid>
To: Francois Daoust <fd@w3.org>
Cc: "mark a. foltz" <mfoltz@google.com>, "public-secondscreen@w3.org" <public-secondscreen@w3.org>
If the ED and WD are kept in sync, what is the difference between the two ?

I thought the general idea was that the ED was, as its name suggests,
what the Editor currently proposes and the WD has working group
consensus.

If our process is that changes are proposed in PRs and only accepted
once there is agreement then the two documents have the same status.
If the process allows the Editors Draft to run ahead of WG agreement
then they should remain different.

...Mark

Sent from my iPhone

> On Jun 9, 2015, at 3:48 AM, Francois Daoust <fd@w3.org> wrote:
>
> 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 14:10:08 UTC

This archive was generated by hypermail 2.4.0 : Friday, 17 January 2020 17:18:56 UTC