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.
process/living-cr-rec.md
Outdated
|
|
||
| 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.
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'm not sure you think there's a suggestion about revision mechanisms, here. Is it because of the presence of "stability"? This section is about the "targeted audience".
I think the line 16 text could also mention this, and the concept of dated versions of Recommendations that can have new features added.
That's addressed in the "Revisions / Maintenance" section.
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.
Good point, I dropped it.
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.
I'm afraid I cannot easily add a "Nigel disapproves" text ;) But I believe the points you raise are captured in the rest of that page, notably "Stability/Availability signals" for adequate implementation experience and test suites. If something's missing, I'm happy to add further considerations.
There was a problem hiding this comment.
I'm not sure you think there's a suggestion about revision mechanisms, here. Is it because of the presence of "stability"? This section is about the "targeted audience".
It's because of:
especially when the expectation is that features will be added to the specification on an ongoing basis
It reads to me as though if this is the expectation then Rec somehow isn't suitable, whereas in fact it offers a specific provision for this case.
There was a problem hiding this comment.
I'll drop that part of the sentence, it was more meant to illustrate former points.
Co-authored-by: Nigel Megitt <[email protected]>
Co-authored-by: Nigel Megitt <[email protected]>
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.