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 <tthibodeau@openlinksw.com>
Co-authored-by: Ted Thibodeau Jr <tthibodeau@openlinksw.com>
Co-authored-by: Ted Thibodeau Jr <tthibodeau@openlinksw.com>
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.
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.