Document substantive changes since Rec as candidate amendments

[dontcallmedom]

This pull request is a proposed approach to document the various substantive changes we've brought to the spec since it was published as a Recommendation to make it acceptable as part of the process to amend W3C recommendations.

---

Preview | Diff

[dontcallmedom]

The process to add a candidate change with this approach is to add a description of the change based on the following template:

<div class=correction id="change-prXXXX">
<p><span class=title><!-- Description that can be used a summary of the change --></span>
   is a candidate correction - 
  see <a href="https://github.com/w3c/webrtc-pc/pull/XXXX">its associated pull request</a>.</p>
</div>

and inserts it in the document close to where the substantive changes were made. It uses the number of the relevant pull request mostly as a way to find an easily-relevant, hard-to-duplicate identifier, but no particular magic is associated with that number at the moment. In particular, if a change is best described as associated to several pull requests, picking any of these as the source of the number can work.

If several distant sections are concerned, further instance of that notice can be inserted by simply adding an empty <div> of the form:

<div class=correction id="change-prXXXX-N"></div>

where N is the incremented value of the number of these notices.

The ReSpec pre-processing script then takes care of adding the numbered "Candidate Correction" markers, and of listing and linking them in the "Candidate Amendments" appendix.

[dontcallmedom]

Reporting from my discussion with @plehegar :

• having a document which integrates seamlessly the candidate (or in the future, proposed) amendments in the normative text is not a priori compatible with the intent of the process
• potential approaches to explore as alternatives that would keep low-editorial friction:
  • generate two documents: a default one with only the "candidate correction" annotations, but not the actual changes, and an informative view where the candidate changes are merged in
  • find a way to provide the two views into a single document (similar to the current approach used by other amended recs with ins/del), but with a much coarser granularity (e.g. at the section level rather than the phrase or in-phrase diff level)

I'll iterate in that direction (probably starting with the latter that would avoid creating confusing doppelgangers)

[dontcallmedom]

@alvestrand @caribouW3 @plehegar I have now taken another stab at this that fulfills the process requirements as I understand them from @plehegar while still reducing the editing burden substantially (although whether it reduces it enough is something I'm looking for @alvestrand feedback).

The result of this work is that:

• the default editors draft view shows the latest content of the spec unchanged https://mir.w3.org/~dom/webrtc-pc/webrtc.html (except for the listing of amendments in appendix)
• when switching to the REC view of the document, it shows in-line candidate corrections, defaulting to showing both current & future, with a toggle to show only the "current" or "future" view, à la https://mir.w3.org/~dom/webrtc-pc/webrtc.html?specStatus=REC#dictionary-rtcconfiguration-members

I've tried documenting the required steps for integrating an amendment in the draft in amendments.md - these steps technically only have to be followed when getting ready to publish a Rec with candidate or proposed amendments (although doing it as we merge substantive pull requests is also possible); my expectation is that this process can be put on the shoulders of the staff contacts rather than editors, since these Rec updates aren't something we expect to do very often in general. From having done it with the current changes, I don't think they're particularly challenging to follow, and certainly less tricky than marking up diffs at the phrase level.

[dontcallmedom]

For illustration purposes, I've gone through the exercise of what it would take to import transferable data channels from WebRTC extensions to the main spec as a candidate addition: dontcallmedom#2 - dontcallmedom@aaed6af is the work needed on top of the spec work to markup the changes as Rec-ready amendments

The same mechanism could be used to bring that section in the editors draft and mark it up as "addition under investigation" there (completely independently of the Rec amendments process), as an alternative to maintaining it in the separate webrtc-extensions repo.

[alvestrand]

how would you mark up a section that is changed multiple times?

[dontcallmedom]

the changes for section id "dictionary-rtcconfiguration-members" in the pull request illustrates a section with two changes. In general, you don't have to mark them up, you just have to describe the changes in amendments.json, and the script takes care of showing the current rec vs the proposed new text.

[dontcallmedom]

@plehegar have you had a chance to check if the results match what you expect would be acceptable for an updated Rec?

[dontcallmedom]

@plehegar indicated offline that this approach should pass muster, so I'm now marking it as ready for review & merging, which will help completing upcoming pull requests with additional substantive changes to document them with this mechanism.

[alvestrand]

Note: the generated version seemed to have a number of respec errors. Those probably need to be hunted down during the merge process.

[dontcallmedom]

I've rebased to main and updated the sample, which removes the said respec errors (the ones that remain are "expected").

[dontcallmedom]

I've updated this with all the latest PR that got merged; it would be great to merge this to ensure new substantive changes can be directly annotated using this mechanism, and to experiment with annotating less mature changes as well (as mentioned in #2770

[dontcallmedom]

merging as agreed with the chairs