Add considerations on the final stage of documents #366
Conversation
This creates a new page in the Guidebook that reviews considerations for Working Groups pondering whether to publish the latest state of their work as Candidate Recommendation (with Snapshots) or as Recommendations. Four dimensions are described: - targeted audience - wide review - stability/availability signals - revisions/maintenance. The revisions/maintenance section could perhaps be expanded and moved to a dedicated page over time. Note: This is intended to supersede #151.
Co-authored-by: Ted Thibodeau Jr <[email protected]>
Co-authored-by: Ted Thibodeau Jr <[email protected]>
Co-authored-by: Ted Thibodeau Jr <[email protected]>
process/living-cr-rec.md
Outdated
|
|
||
| To revise a specification published as a Candidate Recommendation Snapshot: | ||
|
|
||
| 1. A Working Group may publish Candidate Recommendation Drafts at any time and without further review. The drafts can integrate changes directly, there is no need to track substantive changes as candidate amendments. Susbstantive changes still need to go through wide review before another Candidate Recommendation Snapshot may be published, and publication of a new Candidate Recommendation should happen within 24 months of the group making the substantive changes. |
There was a problem hiding this comment.
I suppose mentioning of candidate amendments here about tracking substantive changes are somehow misleading, since candidate-* means changes to mature documents in REC (e.g. definition of candidate amendments), and also groups need to list as changes section.
So, something like (not good example text although)
The drafts can integrate changes directly just with listing as changes, but there is no need to place special tracking similar to candidate amendments.
There was a problem hiding this comment.
Regarding candidate amendments, isn't that what the text already says? If you're at the CR level, you can publish new drafts, and you do not need track updates as candidate amendments, which only apply to REC.
I do not see a requirement to have changes section in the Process for update requests. The Process only requires that class 4 changes be publicly documented. In other words, groups need to track these changes somehow, they don't necessarily need a changelog section in the spec.
Pubrules is slightly stricter than that to make sure that one can find the list of changes from the document itself but also does not require a list of changes in the document itself:
§ It must include a link to changes since the previous draft (e.g., a list of changes or a diff document or both; see the online HTML diff tool).
I guess the text could be amended to insist on the fact that substantive changes need to be tracked no matter what. That was the intent of the mention of wide review, but I agree it goes beyond that in practice.
There was a problem hiding this comment.
I amended the text to note the need to also note the requirement to publicly document substantive changes.
Integrating feedback from @himorin. The text noted the need to take substantive changes made to a CRS through wide review before another CRS can be published. The changes also need to be publicly documented in practice. All in all, while there is no requirement to track changes using the candidate amendments mechanism, this highlights the need to track substantive changes *somehow* once a spec reaches the Candidate Recommendation level.
|
|
||
| Endorsement by W3C as a standard may be a requirement for others to adopt or otherwise refer to a specification. Regulations, industries such as those that produce consumer electronic products, etc., may require organization-level endorsement, guarantees provided by the standards development process, and commitments to the stability of a technical specification. For example, a W3C specification needs to be a Recommendation to be referred to by an ISO standard, or to become an ISO/IEC standard itself through the [PAS Submission mechanism](https://www.w3.org/2010/04/pasfaq). | ||
|
|
||
| On the other hand, some groups may find that the Candidate Recommendation stage aligns more naturally with implementation work that informs the specification development, and with the prioritization mechanisms in multiple (browser) codebases, especially when the expectation is that features will be added to the specification on an ongoing basis. Keep in mind that organizations will still want to refer to these specifications. |
There was a problem hiding this comment.
This suggests that it is not possible to add features to Recommendations on an ongoing basis, but that's incorrect. There's a specific provision for doing so in the Process.
I think the line 16 text could also mention this, and the concept of dated versions of Recommendations that can have new features added.
Also, I don't think that inclusion of (browser) is helpful - it's presuming too much about implementations, and seemingly excluding non-browser implementations that might be appropriate for some specifications.
Full disclosure: I am strongly against the "permanent CR" strategy. If it's not important to get W3C consensus, why bother doing the work in W3C? It's basically a way to get a W3C badge on a document without any requirement even to demonstrate implementability, let alone interoperability. Note that CRs don't have to have test suites, just a commitment to make a test suite.
|
|
||
| On the other hand, there is no adequate implementation experience requirement to publish a Candidate Recommendation Snapshot. It may contain features that are still up for changes, that are not yet available across implementations, and/or that have limited interoperability across implementations. Test cases may not yet be available. | ||
|
|
||
| Adequate implementation experience is key for detecting issues (including privacy and security issues) with a given feature, or lack of support. The web community at large also benefits from clear signals on features. Groups intending to keep specifications at the Candidate Recommendation stage should consider adopting a change policy upon publication of a first Candidate Recommendation Snapshot in the "Status of this Document" section of the document, that sets expectations in terms of adopting, testing and gathering implementation experience for new features. For example, on top of mandatory tests, groups may require explicit support by implementers before adopting a change. |
There was a problem hiding this comment.
I think this is much too encouraging of WGs adopting "permanent CR"!
Although WGs might take this approach from time to time, I think we need to be clear that it's not a suitable endless state to be in.
|
|
||
| Three mechanisms may be used to revise a specification that was published as a Recommendation: | ||
|
|
||
| 1. *Candidate amendments*. A Working Group may include [candidate amendments](https://www.w3.org/policies/process/#candidate-amendments) in a Recommendation at any time, and without further review. These are conspicuously labeled within the specification, and the specification retains its status as a "Recommendation." In order for the group to publish the document as a "clean" Recommendation, there are review steps, after which conspicuous labels are removed, and the candidate amendments are merged. Note: A Recommendation may also include new features provided the text of the original Recommendation set the expectation that this would be permitted. |
There was a problem hiding this comment.
I think the last "also" should be an "only"?
| 1. *Candidate amendments*. A Working Group may include [candidate amendments](https://www.w3.org/policies/process/#candidate-amendments) in a Recommendation at any time, and without further review. These are conspicuously labeled within the specification, and the specification retains its status as a "Recommendation." In order for the group to publish the document as a "clean" Recommendation, there are review steps, after which conspicuous labels are removed, and the candidate amendments are merged. Note: A Recommendation may also include new features provided the text of the original Recommendation set the expectation that this would be permitted. | |
| 1. *Candidate amendments*. A Working Group may include [candidate amendments](https://www.w3.org/policies/process/#candidate-amendments) in a Recommendation at any time, and without further review. These are conspicuously labeled within the specification, and the specification retains its status as a "Recommendation." In order for the group to publish the document as a "clean" Recommendation, there are review steps, after which conspicuous labels are removed, and the candidate amendments are merged. Note: A Recommendation may only include new features provided the text of the original Recommendation set the expectation that this would be permitted. |
| - With Candidate Amendments, groups value the possibility to preserve the Recommendation status. Some like the need to identify, categorize and track changes thoroughly and to assess support for them within implementations, which eases wide review. Others miss the flexibility of being able to update the document as a regular draft, and dislike the need to identify and track changes within the document itself in particular. Some changes may be hard to isolate in the source for identification purpose. Commonly used specification editing tools do not currently help with candidate amendments management. The WebRTC Working Group uses a [post-processing module](https://lists.w3.org/Archives/Public/spec-prod/2024JulSep/0008.html) along with a JSON file that tracks amendments to ease the process. | ||
| - For some groups, the "backing up" approach feels like a downgrade after having made the effort to reach Recommendation. | ||
| - The full revision path enables groups to progress features in different levels at once, and newer levels may be published as delta specifications, as is sometimes done by the CSS Working Group. Maintenance of multiple levels is more demanding. Using multiple branches as [done by the Pointer Events Working Group](https://lists.w3.org/Archives/Member/chairs/2025AprJun/0059.html) can work for groups who want to keep the source of a document in a single folder in their repository. | ||
| - Groups going through Candidate Recommendation Drafts before publishing a new Candidate Recommendation Snapshot appreciate the flexibility, but may struggle with the identification and documentation of substantive changes when they again seek wide review. Once the Candidate Recommendation status has been reached, groups should consider tracking substantive changes more thoroughly, e.g., through labels on issues and pull requests, and by documenting technical design decisions. |
There was a problem hiding this comment.
Maintaining a "substantive changes" document is another helpful technique, where each substantive change made to the specification is accompanied by an addition to that substantive changes document.
5 participants
This creates a new page in the Guidebook that reviews considerations for Working Groups pondering whether to publish the latest state of their work as Candidate Recommendation (with Snapshots) or as Recommendations.
Four dimensions are described:
The revisions/maintenance section could perhaps be expanded and moved to a dedicated page over time.
Note: This is intended to supersede #151.