Simplifying the Updatable REC Process

[marcoscaceres]

Session description

Join us at the W3C TPAC 2024 Tech Plenary to address the challenges and potential solutions for the updatable REC process. We'll focus on the issues outlined in issue #866 and collaborate on making the process more efficient.

Core Challenges:

1. Complex Manual Markup: The requirement for detailed manual markup (e.g., <ins>, <del>, specific classes) is time-consuming and prone to errors, frustrating many editors.
2. Detailed Change Tracking: Extensive documentation and linking for each change add unnecessary overhead, often leading to mistakes and confusion.
3. Inflexible Class System: The rigid classification system complicates the editing process and increases the potential for errors.

Proposed Alternatives:

• Enhanced Automated Tooling: Develop tools that automatically generate the necessary markup from simpler inputs, reducing the manual burden on editors.
• Streamline the Existing Process: Simplify the current markup requirements to lower the entry barrier and reduce the time spent on updates.
• Educational Support: Increase training and support for editors to improve efficiency and understanding of the process.

Additional Strategic Alternatives:

• Discontinue the Updatable REC Process: Consider phasing out the current process in favor of something that aligns better with the working realities of editors while maintaining necessary IPR protections.
• Discourage Use of the Current Process: Officially recommend that the current updatable REC process be used only when absolutely necessary due to its complexity and high overhead.
• Introduce a 'Living Recommendation' Model: Adopt a model similar to the WHATWG living standards, allowing for continuous updates without detailed version tracking and complex markup. But we do it in manner that meets W3C assurances and requirements.

Session goal

Improve process and tooling

Additional session chairs (Optional)

No response

Who can attend

Anyone may attend (Default)

IRC channel (Optional)

#updatable-rec

Other sessions where we should avoid scheduling conflicts (Optional)

No response

Instructions for meeting planners (Optional)

No response

Agenda for the meeting.

No response

Links to calendar

• 2024-09-25, 11:15 - 12:15

Meeting materials

• Minutes

[marcoscaceres]

Cc'ing @fantasai, @plehegar, @ianbjacobs, @dontcallmedom

[tpac-breakout-bot]

Thank you for proposing a session!

You may update the session description as needed and at any time before the meeting, but please keep in mind that tooling relies on issue formatting: follow the instructions and leave all headings and other formatting intact in particular. Bots and W3C meeting organizers may also update the description, to fix formatting issues or add links and other relevant information. Please do not revert these changes. Feel free to use comments to raise questions.

Do not expect formal approval; W3C meeting organizers endeavor to schedule all proposed sessions that are in scope for a breakout. Actual scheduling should take place shortly before the meeting.

[sideshowbarker]

I think the list of Core Challenges with the current REC updating requirements should include:

• No autopublishing. Per https://www.w3.org/policies/process/drafts/#revising-rec, there’s no way at all for a Working Group to directly autopublish/re-publish in-place a REC; instead, the Working Group must request the Team to publish updated versions — even just for typos or other extremely minor editorial fixes.
• No substantive changes without full AC review. Per https://www.w3.org/policies/process/drafts/#change-review, WGs can’t get RF Commitments for any substantive changes to normative requirements without going (back) through full AC review.

“Candidate Recommendations”, in contrast, can be directly autopublished/re-published by Working Groups themselves —with no need to make a request to the Team, and with no AC review needed. Specifically, for “Candidate Recommendations”:

• Working Groups can — without AC review — directly autopublish to the spec version in TR space any changes they want, including substantive changes to normative requirements
• Working Groups can — if/when they have a set of substantive changes they want to get RF Licensing Commitments for — just publish a Snapshot. And even publishing Snapshots doesn’t require them to get AC Review either.

So the issue description’s Introduce a 'Living Recommendation' Model alternative would also necessarily need to allow Working Groups to do what they can already do now with CRs: autopublish directly on their own, without AC review.

I also think the word updatable understates what the actual need is: What’s rightly needed is to make RECs maintainable.

[marcoscaceres]

"Maintained Rec" or something would be great. I have a lot of thoughts and ideas about how we could improve on the current process, while maybe even having something that is "quality better" or "more aligned with the W3C expectations" than what the WHATWG has. I'm excited to discuss.

[sideshowbarker]

💯 to putting the word “Maintained” in the spec-status label — regardless of whether it’s a “REC” or “CR”, or whatever alternative non-arcane/esoteric alternatives to “REC” and “CR” we might hopefully someday finally arrive it. Like, say “Maintained Working Group Specification”, that just describes exactly what it is.

But as far as the goes, I fear there’s unfortunately way too much institutional inertia and “concerns” about every one of the logically descriptive possible alternative labels. Or ”REC” and “CR” apparently have so much existing “currency”.

So anyway, I don’t think we should hold our breath on seeing “Maintained” added to the labeling taxonomy any time soon.

[svgeesus]

The <ins>/<del> model is not too bad for small changes to prose sections.

It is completely inadequate for complex, highly internally linked material such as IDL, CSS properties, and so forth. Putting something inside <del> does not hide it's ID and so specifications fail pubrules due to duplicate IDs. Removing or modifying them breaks internal cross-links or makes them link to the wrong thing.

In my opinion, the current system is suitable only for small wording changes in the prose. I have seen WGs not publish for over a year (while still maintaining an ED which is better than the corresponding Rec) solely because of this issue. It is not clear that better tooling will help (unless it is able to insert and remove IDs as proposed changes are toggled between current and future versions.

[marcoscaceres]

That’s my experience too, @svgeesus. With Geolocation, we thought we would only need to make really small changes… but then a few bugs caused us to rewrite an algorithm which suddenly made for significant changes.

I guess one can’t really know ahead of time if the ins/del thing will work. And yes, IDL changes are not handled well either because it would require special handling by the IDL parser (used by ReSpec and Bikeshed).

[dontcallmedom]

I have now made significant progress in the system we use in the WebRTC WG to manage diffs from the WebRTC Recommendation, with a pending pull request that allows the diff markup to be generated mostly automatically - the only manual work is to add ids to the sections that are amended with substantive changes if they don't have one already.

See what the generated document looks like.

In addition to generating and marking up the diffs with the proper UI control, the WG has started using it to keep track of other process related aspects (whether the amendments are tested for, which is then used to identify which have sufficient implementation experience).

While some of this is a bit ad-hoc, the overall approach should be generalizable to other documents (fairly straightforwardly for respec documents, with a bit more work for bikeshed documents), although it would need not insignificant amount of work of ergonomic and documentation improvements.

[plehegar]

The FedID CG and WG have adopted a process to move things between the CG and the WG. It does not take into account the updatable REC process and it would be good to think about how Updatable REC fit into it.