-
Notifications
You must be signed in to change notification settings - Fork 169
UpdatingLivingStandard
Previously, we could just make the changes to the draft as needed, and it would eventually get published. However, now that the spec is a living standard, we can no longer do this. Each change needs to be annotated as a correction or addition. For an example of what needs to be done, see Amendment Boxes in the Sample W3C Specification
Each change needs an associated ID. The ID will be of the form "c<n>" or "a<n>", where "c" means this is a correction to spec, and "a" means an addition. "<n>" will be the issue ID for the change.
This makes it easy to have unique IDs that are easy to match to the reason for making the change. The title of the amendment box can have a link to the issue. Finally, the body of the box should have a short description. We can make it short because we have a link to the issue which can have much more information on why this is needed.
An example of a correction:
<div class="correction" id="c2359">
<span class="marker">Candidate Correction
<a href="https://github.com/WebAudio/web-audio-api/issues/2359">Issue 2359.</a>
</span>
Fix typo in code; semi-colon is incorrect.
</div>
An addition is similar:
<div class="addition" id="c2359">
<span class="marker">Candidate Addition
<a href="https://github.com/WebAudio/web-audio-api/issues/2359">Issue 2359.</a>
</span>
Fix typo in code; semi-colon is incorrect.
</div>
In some cases, a correction or addition will touch many parts of the spec that are far apart. While it would be nice to have just one amendment box for all the changes, it becomes very hard to figure out what the reason for the change is if the box is very far.
In this case, we propose that each change gets its own amendment box. The id is then c<n>-<m> or a<n>-<m>. That is, we append a number <m> to the id, separated by a "-". This allows us to keep track of all the related changes in the sources. We still use a single link to the issue for the change.
For an example, see #2363.