[GNAP] Extraction of Editor's Notes

[Justin Richer <[e-mail]>]

The editors have gone through the draft document and extracted all of the existing “Editor’s Note” items from the text and turned them into discrete GitHub issues for discussion. Several closely-related notes were collapsed into single issues. Apart from fixing a couple typos or adding context from surrounding text, the text of the editor’s note was pulled verbatim from the document into GitHub. These are all in the project repository’s issue tracker:

https://github.com/ietf-wg-gnap/gnap-core-protocol/issues <https://github.com/ietf-wg-gnap/gnap-core-protocol/issues>

A pull request has been submitted that removes the editor’s note and replaces it with a link to the corresponding GitHub issue:

https://github.com/ietf-wg-gnap/gnap-core-protocol/pull/119 <https://github.com/ietf-wg-gnap/gnap-core-protocol/pull/119>

Each issue’s text contains the current section number and title that the text was extracted from in order to facilitate people finding the appropriate context in which the notes were originally written. However, do note that as Yaron posted to the list earlier today, in general we don’t want to have to refer to things in GitHub issues by section number, since the section numbers can and will change over time as the document evolves. Therefore future issues should avoid including section numbers, and must not rely on section numbers as the only content reference pointer.

This extraction was done to facilitate ongoing conversation on each of the items raised by the notes. Notational text in the document itself is necessarily static, and it can’t incorporate multiple perspectives and opinions. Moving these items to GitHub issues will allow others to comment on the issue directly to provide their own opinions, input, and contexts; and ultimately for the working group to arrive to consensus and drive document changes from these discussions.

The editors will eventually remove the issue references from the spec as things are closed, and we won’t necessarily be adding links to new issues into the draft spec going forward unless there is a compelling reason for it like an ongoing discussion for options or a major design change.

 — Justin, Fabien, and Aaron