- From: Dominique Hazael-Massieux <dom@w3.org>
- Date: Thu, 2 Mar 2023 22:28:13 +0100
- To: spec-prod <spec-prod@w3.org>
Hi, Back on November 2021, there was a discussion on this list on how challenging it can be to maintain candidate and proposed amendments in markup for the new post-Rec update process: https://lists.w3.org/Archives/Public/spec-prod/2021OctDec/0028.html I have been since experimenting with an alternative approach that was used successfully by several contributors to document the set of candidate corrections and additions that were published in the updated WebRTC Rec yesterday: https://www.w3.org/TR/2023/REC-webrtc-20230301/#changes The way this works is that the editors draft of the spec is edited directly to incorporate the desired changes in the body of the spec. Along with making these changes through pull requests, they get described in an ad-hoc JSON file: https://github.com/w3c/webrtc-pc/blob/main/amendments.json https://github.com/w3c/webrtc-pc/blob/main/amendments.md This spec is developed with ReSpec, so I developed a little ReSpec post-processing module that uses that JSON file and a static copy of the initial Recommendation to generate the diff-like view embedded in the udpated Rec above (along with the list of amendments in the appendix): https://github.com/w3c/webrtc-pc/blob/76392ed30bebde812702a704b104cb792c6d5ff2/webrtc.js#L127 (I haven't experimented with it, but I'm reasonably confident the same code could be applied to post-process a bikeshed document with similar results) This is further assisted by a github action that requires any pull request that isn't labeled as "editorial" to be listed in the amendments: https://github.com/w3c/webrtc-pc/blob/main/.github/workflows/track-rec-changes.yml There remain a some limitations with the system: * The markup and JSON changes that editors have to manage aren't always as straightforward as I would want * The resulting diff aren't as granular as a word-for-word diff would be, and in some cases can end up being pretty large, e.g.: https://www.w3.org/TR/2023/REC-webrtc-20230301/#dictionary-rtcconfiguration-members But since these diffs are completed by links with the underlying pull requests, which themselves have in general a useful description of the change, I think that's probably a manageable outcome. I'm sharing this here in case it can serve as inspiration for other groups; I don't think the system is quite yet at a stage where it would be worth baking it into spec-authoring systems, but hopefully with more experimentation and iteration, this could be a starting point to that. Dom
Received on Thursday, 2 March 2023 21:28:17 UTC