search

w3c / did-core

W3C Decentralized Identifier Specification v1.0
https://www.w3.org/TR/did-core/
Other
395 stars 93 forks source link

Clarify that appendices are non-normative. #796

Closed msporny closed 18 hours ago

msporny commented 2 years ago

This PR fixes issue #791 by explicitly marking all appendices are non-normative.

I will merge this PR as soon as I have confirmation from the Chairs and Staff since this is a purely editorial change with no additions nor changes to existing specification text.

Preview | Diff

Preview | Diff

msporny commented 2 years ago

Super picky: As all subsections of say, App B are marked as non normative, it may not be necessary to add B (or C) as non normative. Just to be consistent with App A, where this isn't done (or, alternatively, add the same to App A as well).

Fixed in https://github.com/w3c/did-core/pull/796/commits/a9349a7a64a1a0784dbd839b61b3ef8f0376a099.

I had gone with your first suggestion (just make the top-level appendix non-normative) at first... but we had two people complain that "just because the top level is non-normative doesn't mean the sub-section is non-normative. So, I just went with being very explicit and put it in each major and minor section.

Does that address your concern, @iherman?

iherman commented 2 years ago

Does that address your concern, @iherman?

Yep, thanks!

talltree commented 2 years ago

For future reference, when all subsections of a section are non-normative, I would recommend putting a single statement at the start of the top-level section saying, "This section and all subsections of this section are non-normative."

msporny commented 2 years ago

For future reference, when all subsections of a section are non-normative, I would recommend putting a single statement at the start of the top-level section saying, "This section and all subsections of this section are non-normative."

Yes, totally agreed, and that's what we used to do. A small vocal minority of readers of the specification asserted strongly that doing so is not enough :(, which is why we're going with the current approach.

TallTed commented 2 years ago

s/appencies/appendices/ in the title of this PR?

msporny commented 18 hours ago

Class 2 change, editorial, multiple reviews, changes requested (but not made due to initial issue), no objections, merging.