Re: Moving the new publication process

On 2015-06-09 19:25, mark a. foltz wrote:
> I think I concur with MarkW, I think a semi-automated process where it's very easy to publish a new WD, but there's still someone who has to flip the switch.  Just because there's a commit doesn't mean the document is in a self-consistent state.  For example landing a particular spec change may be spread across multiple commits, or there may a few iterations before getting to a consensus change.

Right. The "spirit" of the new publication system is that:

- inconsistent states will be temporary and will typically be fixed during the day. In practice, the system will only preserve the latest published version in /TR/ on a single day. In other words, if you publish the spec 5 times in a row on a given day, the only version that will remain in /TR/ space will be the fifth one. The first four inconsistent versions will just be published for a short amount of time and will not remain in /TR/ history.
- a "working draft" is unstable by definition, so the fact that it may not be consistent or that it may not fully represent the WG consensus is not a big deal (as long as WG participants are fine with that). It becomes a big deal when the spec gets published as a Candidate Recommendation, but we won't be allowed to publish updates to a Candidate Recommendation automatically (or even manually without due process).
- the existence of outdated drafts in /TR/ space has done more harm than good and many people consider it more useful to have potentially inconsistent but recent drafts in /TR/ space than to have consistent but outdated ones.
- editors are trustworthy :)

That said, I'm perfectly fine with any mechanism that you might want to follow.

>
> So I would vote for c).

OK. Whatever the option, it all starts with making a few updates to the spec and possibly Makefile to ease the work. I'll work on that.


>
> An alternative mechanism to keeping parallel copies would be to use git branches:  The editor's draft becomes a branch and we periodically merge commits to gh-pages (which becomes the working draft).  There would need to be some automation to fix-up gh-pages after a merge (updating dates, links) to meet the pubrules.

The one thing that I do not like with this mechanism is that it becomes more cumbersome for WG participants to take a look at the most recent version, since they would have to pull the editor's branch locally to view it.

Yet another mechanism would be to use a tag but that would mean that index.html would appear as Working Draft despite potentially being much more recent than the Working Draft published in /TR/ space.

The merge should be relatively easy in any case, as the only parts that should change are the link to the stylesheet, the date, and the "this version" and "previous version" links (the editor's draft should be pubrules compliant otherwise).

Francois.

>
> m.
>
>
>
> On Tue, Jun 9, 2015 at 7:09 AM, Mark Watson <watsonm@netflix.com <mailto:watsonm@netflix.com>> wrote:
>
>     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 <mailto: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 20:35:44 UTC