UpdatingLivingStandard

Updating the Living Standard

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

Adding Amendment Boxes

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.

Examples

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 
</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>

Complicated Updates

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. In summary, though, do something like:

<div class="correction" id="c2361-7">
  <span class="marker">Candidate Correction
  <a href="https://github.com/WebAudio/web-audio-api/issues/2361">Issue 2361-7.</a>
  </span>
  Use new Web IDL buffer primitives
  <div class="amendment-buttons">
    Buttons here
  </div>
</div>

The "amendment-buttons" will get replaced with previous/next buttons to allow readers to navigate through related changes, as shown in the preview for #2363.

Broken Links

Sometimes the spec needs to be updated because an old link no longer works. If we follow the approach above and use <del> to remove the old link and text, bikeshed will still complain about the old link no longer existing. Perhaps the best solution here is that we remove the link itself, but leave the link text in so we can see what changed between the old and new versions. Of course, we don't get the link, but it wouldn't work anyway.

Updating Change Log

With each correction/addition, the ChangeLog must be updated as well. For example, add something like this:

  * <a href="https://github.com/WebAudio/web-audio-api/pull/2361">PR 2361</a>: Use new Web IDL buffer primitives
    <div id="change-list-2361">
    </div>

where this is the change log caused by PR 2361. The <div> is where a list of all relevant changes are listed. At the bottom of index.bs, update the listener function to get the list created automatically for the change.

<script>
window.addEventListener('load', (event) => {
  ListAmendments("c2361", "Correction", "change-list-2361");
  });
</script>

This will find all of the changes whose id begins with "c2361" and creates a list of them using "Correction" as the prefix. "change-list-2361" is the ID of the div where the list should go.

The generated html result will look something like:

<ul>
  <li> <a href="#c2361-1">Correction 1</a> </li>
  <li> <a href="#c2361-2">Correction 2</a> </li>
  <li> <a href="#c2361-3">Correction 3</a> </li>
  <li> <a href="#c2361-4">Correction 4</a> </li>
  <li> <a href="#c2361-5">Correction 5</a> </li>
  <li> <a href="#c2361-6">Correction 6</a> </li>
  <li> <a href="#c2361-7">Correction 7</a> </li>
</ul>

Issues

• Currently, previews won't show the list in the change log because of a bug in bikeshed that causes bikeshed to treat the <script> element as regular bikeshed text. This mangles the JS code. For now, the necessary JS code is in the file "amendments.js" which isn't uploaded to the preview server.
• Amendments don't always have the insertions and deletions marked correctly if there are links in the insertion or deletion. Not sure if this is an issue with amendment fixup.js or with bikeshed's CSS or some other issue.