W3C

Publication Workflow

Context

Publishing a document into the W3C /TR space can be challenging. Once you've got the decision from the Group and/or the Director to publish, it could take several asynchronous back-and-forth before you and the webmaster before the document is ready for publication. In addition, this publication pipeline model doesn't allow for rapid updates, thus contributing to the sentiment (and a good chunck of reality) that /TR mainly contains old documents. Yet, the W3C Process Document doesn't say that one cannot publish a Working Draft every single day if the Working Group is ok with it. The proposed publication workflow is driven by 3 main motivations:

  1. Simplify the "Art of W3C Publishing" (getting your document published in /TR)
  2. Allow Working Groups to update their drafts as often as needed
  3. Reduce the W3C team resources overhead when publishing

It is important to note that, when discussing documents published in /TR, there are several topics that could come up in addition to the publication workflow proposal:

  1. Editing tools: respec, bikeshed, anolys, etc.
  2. Pubrules tool: see specrebus
  3. /TR redesign: JSON API, style sheets, etc. (being worked on separately as well)
  4. Latest version semantic: latest published, latest modified, latest approved
  5. Living Standard vs Snapshots
  6. W3C Process issues
  7. CC0, CC-By, W3C Document License, etc.
  8. How to get Working Group or Director's approval
  9. Old Working Drafts on /TR and search engines (will get addressed in 2015…)

if you are interested in these topics, see Publications, but we scoped the proposal to the 3 main motivations cited above.

How does it look today?

Well, your path to get the document published by the webmaster will most likely start with an email as follows: 

To: webreq@w3.org
From: You

 Dear webreq,

 This is a publication request for 
   http://example.org/my-draft-is-ready.html

 Please publish it this upcoming [Tuesday|Thursday],

 Thank you,

 Me

... and then the troubles start. The pubrules checker will most likely complain and the webmaster will come back to you in certain of hours or days asking you to fix them. You try to fix them, and start again with another email.

Yet, the publication requirements are relatively easy to summarize:

Future Publication workflow

So, what can we do to change the publication pipeline. The first thing to note is that we need to accommodate the most extreme cases:

  1. From "Every single edit generates a Working Draft" (per previous Group consensus decision), ie ability to integrate our publication pipeline in existing editing workflows;
  2. To "FPWD, CR, PR, and REC needs to be approved by the Director", ie we still need some minimal human checks by the Webmaster and Comm;

… while also allowing middle ground cases depending on the Groups, like some Working Drafts will need Team Contact or Domain Lead approval

As mentioned earlier, our goal here is not to revamp how one gets the approval from the Working Group, Director, etc. We do however intend to include the approval of the webmaster and Comm in the workflow.

Given the 1 August 2014 Process and the publication requirements cited earlier, we came with 3 workflows:

FPWD Workflow

  1. Individual completes the Request Form;
    • if not specrebus ok, fix and repeat
  2. Webmaster validates publication
    • if error, fix and go back to step 1
  3. document is published at given date automatically.
  4. Folks get notified

General WD Workflow

  1. Individual completes the Request Form;
    • if not specrebus ok, fix and repeat
  2. document is published at given date automatically.
  3. Folks get notified

Other cases

  1. Individual completes the Request Form;
    • if not specrebus ok, fix and repeat
  2. Comm validates publication;
    • if error, fix and go back to step 1
  3. Webmaster validates publication
    • if error, fix and go back to step 1
  4. document is published at given date automatically.
  5. Folks get notified

And given the 3 workflows cited above, the interfaces would roughly look like below. All actions on the system will get logged.

Publish a First Public Working Draft

Link:
Domain Lead approval:
Short description:
Request exception:

We expect Team Contacts and Domain Leads to be authorized to press the button.

CR/PR/REC/PER

Link:
Director's approval:
AC draft announcement:
Request exception:

We expect Team Contacts and Domain Leads to be authorized to press the button.

WD (non-automatic) (and non-substantive CRs)

Link:
Request exception:

For non-substantive CRs, we'll add a checkbox so the individual can assert that the changes are only non-substantives.

We expect Team Contacts, Domain Leads, Chairs, and Editors, and automated hooks to be authorized to press the button. We will also make sure to have an UNDO form as well in case someone published the document when they shouldn't have done so. All parties will get automatically notified if a publication occurs.

Setup automatic WD

Latest version:
Staging URI:

You can get a ping URI in return. HTTP POST on ping URI would trigger a publication. All parties will get automatically notified if a publication occurs.

Note: We don't do automatic CR yet since the individual needs to assert that no substantive changes were introduced.

Dated versions

Additional Requirements for Editors

Those are targetted at preserving the security of the domain w3.org and simplifying the resulting tools down the pipeline (such as the /TR JSON API).

  1. No third-party resources (JS, trackers, etc.) unless whitelisted
  2. Additional metadata to avoid guesses and ambiguities: Editor's Ids, etc.

Dependencies

  1. third-party checker: TBD (based on phantomjs?)
  2. pubrules checker: specrebus issues list
  3. additional rules for identifying or providing metadata (we'll try to keep those to a minimal)
  4. getdocrdf rewrite (that's the 15 years-old tool that grabs all metadata from a /TR document)
  5. Link checker: current link checker may need a rewrite

Timeline

Transition phase

We don't intend to comply with the 2005 version of the W3C Process in our V1 version. In other words, we'll make it works for the 2014 version only. If you need to publish a Last Call Document, you may have to use the old ways, which we don't intend to retire for the time being.

Appendix

Fetching the document

The algorithm used to fetch a document should work as follows:

  1. GET http://example.com/staged/manifest.txt
  2. If 404, GET http://example.com/staged/my-staged-document (or http://example.com/staged/ depending on what you gave us)
  3. otherwise fetch all the entries (relative links) in the manifest while respecting sub-directories

(see Copying drafts in W3C space)

Working Drafts and Patent Policy

In case you wonder why we care a lot about publishing Working Drafts, here is a quote of the W3C Patent Policy that indicates why they count:

If a participant leaves the Working Group later than 90 days after the publication of the first public Working Draft, that participant is only bound to license Essential Claims based on subject matter contained in the latest Working Draft published before the participant resigned from the Working Group.

Section 4.2, Exclusion and Resignation From the Working Group

Group consensus and decision

We're not in the business of telling Working Group how or when they reach a decision to publish. We MAY however want to the Group to properly record their decision to publish systematically.

must record the group's decision to request publication. Consensus is not required, as this is a procedural step.

Section 7.3.2, Revising Public Working Drafts