Organize first round of Review Drafts

[othermaciej]

It's now been almost 4 months since the start of the WHATWG IPR Policy. We should figure out how to get a round of Review Drafts published in June, 2018.

[annevk]

So these should be analogous to https://fetch.spec.whatwg.org/commit-snapshots/0dec453f642c1fe57e6e7627c9a66cf7f8b8394d/ so we want to use a modified set of https://github.com/whatwg/whatwg.org/blob/master/resources.whatwg.org/build/deploy.sh instructions.

Per https://whatwg.org/workstream-policy#review-drafts they might require some modifications so we should put them in git.

Should we just create a review-drafts/ directory in each standard repository and manually generate a copy in there every six months and commit it via a PR? And ensure it gets published in an equivalent directory on the site?

[domenic]

The review-drafts/ directory seems fairly reasonable.

We'll also need a new Bikeshed template, status, and stylesheet.

[othermaciej]

Yes, it would be pretty analogous to commit snapshots, but with a few differences:

• Needs some different boilerplate text, per the Workstream Policy
• We may want slightly different, less flavorful styling

Hopefully we can make the production process as low effort as possible.

[annevk]

Yeah, I think we can make it so that make review from within the specification directory does the right thing. Then all you need to do is commit that on a branch and create a PR for it.

We could consider even more automation, but that seems like a good first step.

[othermaciej]

We'll want to keep all the review drafts around, I think, so probably need a unique (date stamped?) filename for each one, instead of overwriting the same one. (Maybe this is already what you had in mind.)

[annevk]

Yeah, review-drafts/{year}-{month}/ is what I had in mind. That does mean that if you run that twice in the same month, you'd overwrite, but since master is typically protected that would be caught during the PR if not earlier.

[geoffcr]

The IPR Policy starts a review clock upon posting of the Review Draft, so a persistent time-stamp would be a good thing.

[annevk]

@geoffcr hmm, there'll be a timestamp in git for sure and while we could in theory put one in the document, given that we first post it as a PR before publishing it it would get out-of-date. I guess we could push a small fixup commit just before landing the PR, but it might still be a couple minutes apart from when it's reachable on the site.

[othermaciej]

It's probably ok for the timestamp to be only approximately accurate (say, to the day or the the hour).

[annevk]

If day is okay that would be perfect, as we provide that for all documents we publish already.

[annevk]

I created whatwg/whatwg.org#197 for the more technical aspects of this discussion.

[domenic]

One thing that I wonder is whether we should include various non-normative things since they're not important for patent review. For example:

• The two indices of terms
• The IDL index
• The table of contents
• All domintros (The "For web developers (non-normative)" sections)
• All notes and examples

I'm assuming for now we'll keep all of these. But I'd welcome others' thoughts. I am especially unsure on the indices and domintros.

Edit: on further thought, including sections marked explicitly "for web developers" in a document not intended for them seems bad. We should probably get rid of those at least.

[othermaciej]

My opinion:

I'm pretty sure indices and the table of contents are useful for legal review. One of the first things patent attorneys look for in a standards document is an overview of what it covers. Afterwards, it's important to be able to look things up by topic or term.

Non-normative notes, examples and intros are not as essential to navigate and break down the document. But they are useful to the extent they clarify the intent of the normative requirements. Intent is often relevant in a legal context, especially when disambiguating otherwise ambiguous language.

In general, removing things to try to make the document harder to use for various purposes does not seem worthwhile. The prominent warning on Review Drafts already makes the WHATWG position clear. If someone chooses to disregard it, at that point it's their problem. We don't want to mislead people, but we don't need to try to force them to only use the document the way we want.

[annevk]

When can a Review Draft be modified? Only prior to publication?

[vfournier17]

I agree with @othermaciej.

[vfournier17]

@annevk - Yes, a Review Draft should only be modified prior to publication. It needs to be static after that so everyone is referring to the same document.

[othermaciej]

At the very least its substantive content shouldn't change once it is published. It is ok to have some form of early staging version. It might be ok to change cosmetic/styling aspects or non-normative front matter after publication.

[annevk]

Okay, @domenic and I are mostly done with all the tooling around Review Drafts. Review whatwg/meta#92 for a more detailed status and some nice-to-have features that are not yet covered (and likely won't be for this round).

Given that, coupled with me not having much later in June, I'd like to go ahead and publish Review Drafts next week. I suspect I'll get them all out on Tuesday per the process outlined at https://github.com/whatwg/meta/blob/master/MAINTAINERS.md#review-drafts. @domenic will likely help with review.

Please let me know if you have any concerns.

[vfournier17]

From a legal review perspective, I don't think we anticipated reviewing all of the specs at the same time. Could we stagger them? @geoffcr @ishnaneamatullah What are your thoughts?

Is Mika on GH?

[geoffcr]

I think we were leaning toward staggered rather than all at once - but I'm not sure we'll know until we try.

[vfournier17]

We need to have these staggered, as we would not be able to conduct a patent review of all of them in 45 days. We talked about this when we were putting the documents together. The Review Drafts don't all need to go out at exactly 6 months the first time. Maybe 5 per month for the next 3 months?

[annevk]

I'm not available mid-June mid-July, but otherwise happy to assist. There's nothing in the policies about staggered publication though and the policies put it all on the editors which are largely independent per Workstream (at least in theory), so there might be some cleaning up to do there.

Could you propose 5 Living Standards to publish as Review Draft next Tuesday? I guess we can sort out when to do the next round after that.

[vfournier17]

We'll talk about this at today's counsel meeting and let you know. Thanks.

[vfournier17]

@annevk We discussed the staggering at the counsel meeting, and we'd like to group the Review Drafts into three chunks. This would spread out the patent reviews so participants would not have to review 15 Living Standards at once, and would help ensure that the review periods for the larger Living Standards, such as DOM and HTML, would not occur at the same time.

We propose the following three chunks of Review Drafts, to be released at roughly the same time of the month in June, July and August:

• The first chunk would include: Compatibility, Console, DOM, Encoding, Fetch.

• The second chunk would include: Fullscreen API, HTML, Infra, MIME Sniffing, and Notifications API.

• The third chunk would include: Quirks Mode, Storage, Streams, URL, and XMLHttpRequest.

Does this sound feasible?

[annevk]

Here are dates that work for me that also meet those requirements:

• First: June 19-22
• Second: July 23-25
• Third: August 21-23

I'd want to publish on the first day of any given window above, but that leaves some room for problems.

@domenic or @foolip will also need to be available, primarily to review. (We could switch those roles, but for any given window above, we need at least two people.)

[foolip]

I will be around June 19-22, the other dates are too far out that I haven't decided on vacation time and stuff.

[domenic]

I currently have no plans for those dates.

[vfournier17]

Those dates sound fine. Thanks very much for accommodating!

[annevk]

As these are all published, closing this. We're about to publish a new round: #86.