Add support for candidate additions/suggestions

[marcoscaceres]

Part of process 2021 is to have boxes things labelled candidate additions (similar to notes... but they need to be called out).

Only supported on Editor's drafts and REC docs.

If .addition is present, add to the SoTD:

<p>
        This specification includes <a href=
         "https://www.w3.org/2020/Process-20200915/#candidate-addition">Candidate
         additions</a>, which are marked in the document.
</p>

[msporny]

@marcoscaceres raised some questions that are helpful wrt. requirements for this feature:

• where should we gather the list of candidate corrections/additions?

There seem to be four classes of things: candidate corrections, candidate additions, proposed corrections, and proposed additions. I'm still not clear when you use the former vs. the latter (I've read through the relevant sections in Process 2021 about six times now and it still hasn't stuck).

• where should we gather the list of candidate corrections/additions? In the SoTD? In their own section?

At present, it looks like there is no list required. I've started adding a "Revision History" appendix to specs that might go through candidate corrections and hand-editing a list there:

https://htmlpreview.github.io/?https://github.com/w3c/vc-data-model/blob/main/REC/2021-11-09/index.html#revision-history

We've also splattered these proposed corrections throughout the spec:

https://htmlpreview.github.io/?https://github.com/w3c/vc-data-model/blob/main/REC/2021-11-09/index.html#c1.1 https://htmlpreview.github.io/?https://github.com/w3c/vc-data-model/blob/main/REC/2021-11-09/index.html#c1.2 https://htmlpreview.github.io/?https://github.com/w3c/vc-data-model/blob/main/REC/2021-11-09/index.html#c1.3 https://htmlpreview.github.io/?https://github.com/w3c/vc-data-model/blob/main/REC/2021-11-09/index.html#c2.1 https://htmlpreview.github.io/?https://github.com/w3c/vc-data-model/blob/main/REC/2021-11-09/index.html#c2.2 https://htmlpreview.github.io/?https://github.com/w3c/vc-data-model/blob/main/REC/2021-11-09/index.html#c3.1 https://htmlpreview.github.io/?https://github.com/w3c/vc-data-model/blob/main/REC/2021-11-09/index.html#c3.2

Note that while I did the above, the Team still hand to go through and upgrade what I did to something that provided a diff/old/new view with fancy buttons to switch between them. While that approach makes it really easy for reviewers, it's painful for Editors and the WG Members that typically just provide PRs w/ changes.

• What do we do about inline corrections? base.css doesn't say it supports "span" elements, for instance.

My process was:

1. Prepare the revision of the REC.
2. Run htmldiff against oldREC and newREC.
3. Hand-copy the substantive diffs to a static copy of newREC.
4. Add the new fancy correction class on a div above the diff-marked change. Generate an identifier by hand that had a major and minor number associated with it (for example, if there was a general proposed correction that affected 3 parts of the spec, the markers would be c1.1, c1.2, and c1.3). I have no idea if that's helpful or not.
5. The Team had to come back in behind me and wrap diff/old/new buttons and content manually.

All of that took 12 hours, because I got it wrong twice before I got the Team something they could work with.

• Should people be using ins/del for these? Apparently, from a discussion elsewhere, those elements are not accessible.

Oof on the "not accessible", no idea how to address that... we should ask the a11y folks for suggestions.

What I submitted to publishing used ins/del along w/ UTF-8 (up arrow for insert, down arrow for delete, updown arrows for change). I had to hand copy these over to the static version from an htmldiff'd copy of the spec.

• Should we have a shared JS library?

Yes, please.

Who will maintain it?

I'm willing to take a shot at a diff'ing extension to ReSpec... but I expect high chance of failure there. I'm not so sure I like this new approach, I think it's far too error prone to be scalable. Where is this diff-mark-only-the-substantive-changes requirement coming from? Are they aware of how painful it is for an Editor to train a WG to do the right thing here?

[marcoscaceres]

Ok, this approach is interesting and not at all what I was expecting: that is, I was not expecting a box describing the rationale for the changes. Rather, I was imagining that each box would just contain the "addition" or "correction" being made... the reason why something changed is, IMO, somewhat redundant because that would be tied to an issue or pull request on Github: those would then be shown in the change log.

When the diff is then generated, it only contains the changes.

WDYT?

[marcoscaceres]

Just to straw-person this out:

• If there is a deletion, them just delete (will show up in htmldiff and in changelog).
• If it's a "correction", add <span class="proposed correction"> and simply correct the text, deleting whatever text was there.
• If it's an "addition", then wrap with <div class="proposed addition"> or <section class="proposed addition"> for the addition... or use any container element. If it's an inline, use a <span class="proposed addition">.

Finally, add a <rs-changelog from="REC">.

[marcoscaceres]

(about "candidate" VS "proposed" ... yeah, that's confusing... I'll have a read... but that sounds like there should only be one)

[fantasai]

Candidate vs Proposed is distinguishing which changes the WG is proposing for review/implementation (WD/CR-phase) and which they are proposing for AC review (PR-phase). The reason for this is that for larger specs especially, there might be a lot of fixes that the WG wants to make, but some of them don't yet satisfy all the review/implementation requirements to be folded into a REC. Those that do, get marked as Proposed and are submitted to the AC for approval (and after said approval, can be folded into the spec in its next publication). Those that don't have to stay marked as "changes we are planning to make to this REC" (and are treated as WD text wrt Patent Policy).

What goes into the box is an explanation of the change. Whether it's explaining what the change is, or also the rationale, is up to the WG. The point is to make sure that the change is understandable to the reviewers. Actual diffs can be either put into the box or embedded in the document. See https://www.w3.org/StyleSheets/TR/2016/README#amendment If they are correctly marked up, fixup.js will be able to generate the buttons for switching the view. Also, diffs aren't actually required, as long as the exact changes to be made are understandable from the explanation. For example, updating a reference from A to B can be explained as that; diffing out the entire document isn't needed, as long as it's clear enough from the explanation what the exact text of the final document will be after the change has been folded in.

As far as tooling support for changes, I think a tool that reads in a patch file and spits out source that is diff-marked with a given cite identifier would be helpful (maybe with a switch as to whether the patch needs to be reversed out first). That allows the editor to adjust the diffs after the automation, which is important since automated HTML diffs are sometimes very convoluted.

I think Manu's case is the toughest: trying to publish a spec that's accumulated many changes prior to adoption of P2020. Cases like that, the WG might want to consider taking the old path for updating a REC, which is returning it to CR, then PR, then REC; rather than using the amendment process which is optimized for amending the REC as you go, and being able to keep the changes visible on /TR as soon as the WG has resolved on them.