Re: Moving the new publication process

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.

So I would vote for c).

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.

m.



On Tue, Jun 9, 2015 at 7:09 AM, Mark Watson <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> 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.
> >
>