Re: Managing candidate/proposed amendments

Le 02/03/2023 à 22:28, Dominique Hazael-Massieux a écrit :
> 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.:

As described in 
https://github.com/w3c/tpac2024-breakouts/issues/11#issuecomment-2324941595 
and https://github.com/w3c/webrtc-pc/pull/2995 , the latest update to 
the system addresses these limitations quite significantly from my 
perspective.

Thanks to the JS library TC39 uses to manage diff in their own spec 
environment, I'm now able to produce much more granular diffs, as 
illustrated in:
   https://codepen.io/dontcallmedom/pen/vYqVxqe?editors=0010

Dom

Received on Tuesday, 3 September 2024 06:27:13 UTC