Guidelines for Writing an IANA Considerations Section in RFCs
draft-leiba-cotton-iana-5226bis-20

[Ballot discuss]
My previous DISCUSS mentioned that I don't understand "current important information" in section 1.2
I disagree that  "includes current *important* information from IANA."
This sounds like this URL is more important the BCP. If it's important, it should be in this document or a bisbis document.
As far as I can tell (I've been trying to get some clarifications with my previous DISCUSSes, and the home page is still empty), this URL will "only" contain: current clarifications, minor updates, and summary guidance.
I see this sentence...

      Any significant updates to the
      best current practice will have to feed into updates to BCP 26 (this
      document), which is definitive.

"significant updates" contradicts "current important information".  Ok, it depends how you interpret those two terms .
Proposal.
OLD:

  IANA maintains a web page that includes current important information
  from IANA.  Document authors should check that page for additional
  information, beyond what is provided here: current clarifications,
  minor updates, and summary guidance.  Any significant updates to the
  best current practice will have to feed into updates to BCP 26 (this
  document), which is definitive.

NEW:

  IANA maintains a web page that includes additional clarification
  information, beyond what is provided here, such as minor updates and
  summary guidance. Document authors should check that page.
  Any significant updates to the best current practice will have to feed
  into updates to BCP 26 (this document), which is definitive.

[Ballot discuss]
My previous DISCUSS mentioned that I don't understand "current important information" in section 1.2
I disagree that  "includes current *important* information from IANA."
This sounds like this URL is more important the BCP. If it's important, it should be in the bis document.
This URL "only" contains: current clarifications, minor updates, and summary guidance.
I see this sentence...

      Any significant updates to the
      best current practice will have to feed into updates to BCP 26 (this
      document), which is definitive.

"significant updates" contradicts "current important information".  Ok, it depends how you read those two terms .
Proposal.
OLD:

  IANA maintains a web page that includes current important information
  from IANA.  Document authors should check that page for additional
  information, beyond what is provided here: current clarifications,
  minor updates, and summary guidance.  Any significant updates to the
  best current practice will have to feed into updates to BCP 26 (this
  document), which is definitive.

NEW:

  IANA maintains a web page that includes additional clarification
  information, beyond what is provided here, such as minor updates and
  summary guidance. Document authors should check that page.
  Any significant updates to the best current practice will have to feed
  into updates to BCP 26 (this document), which is definitive.

[Ballot comment]
- Section 3.2

  In such cases, the document defining the namespace must clearly state
  who is responsible for maintaining and updating a registration.
  Depending on the registry, it may be appropriate to specify one or
  more of:

Isn't it confusing that we're covering the content of section 2.3 again?



- Section 5.4

  For registrations made from documents on the Standards Track, there
  is often expert review required (by the registration policy) in
  addition to IETF consensus (for approval as a Standards Track RFC).
  In such cases, the review by the designated expert needs to be
  timely, submitted before the IESG evaluates the document.  The IESG
  should generally not hold the document up waiting for late review.
  It is also not intended for the expert review to override IETF
  consensus: the IESG should consider the review in its own evaluation,
  as it would do for other last-call reviews.

The last sentence applies to all registrations, not only Standard Track, right?
Ex: Experimental or Historic.

One the same topic of consensus versus DE review, I see this text:

  Reasons that have been used to deny requests have included these:

  o  Scarcity of code points, where the finite remaining code points
      should be prudently managed, or where a request for a large number
      of code points is made and a single code point is the norm.

I faced the situation where the WG consensus was to allocate code points while the DE disagreed, based on the scarcity argument.
In the end the consensus win.
Just one observation that there are two types of "Reasons that have been used to deny requests have included these"
The ones that consensus would trump (subject to discussion):

      o  Scarcity of code points, where the finite remaining code points
        should be prudently managed, or where a request for a large number
        of code points is made and a single code point is the norm.

      o  The extension would cause problems with existing deployed systems.

... and the other reasons where the DE has all the rights to push back: documentation, conflicts, etc.


Potential improvements:
- I wonder whether a sentence or two regarding the IANA verification at IETF LC (you know, the email such as [IANA #ticket-number] Last Call:  (draft title) to Proposed Standard) would not be welcome. This would stress that a WG LC will trigger a discussion between the authors and IANA regarding the content of the "IANA Considerations" section, to be solved before the draft arrives on the IESG table.
- "Early Allocation Assignment Expirations Report" email, sent by Michelle Cotton on regular basis:

    In accordance with the proposed 2016 SLA, below is the monthly report on the expiration of early allocation assignments in IANA-maintained registries. This message is for your information.  A report will be delivered once per month.

   
    IANA has identified two early allocations that, in accordance with RFC 7120, will expire soon.

While not completely related to "Guidelines for Writing an IANA Considerations Section in RFCs", I wonder if it makes sense to say a few words here. Mixed feelings about that one. It should really be in 7120bis, but not sure we want to update this RFC just for this sentence.

  It is not IANA's responsibility to track the status of allocations,
  their expirations, or when they may be re-allocated.

[Ballot comment]
Thanks for addressing my DISCUSS and comments. I have just two further comments about Section 1.3:

#3 under "In general" -- An author's first stop should be a WG chair or document shepherd, not an AD.

#7 under "existing registry" -- I think this needs some qualification, such as "If the item contains contact information for a person, make sure it's clear ...." Otherwise I think this could confuse people into thinking that they need to say something about registration policy when all they're doing is registering a value in an existing registry.

[Ballot comment]

Thanks for handling my remaining discuss point.

I didn't check these comments for -17, happy to chat about
any that remain relevant. (Or to not chat about 'em if that's
not needed:-)

- Almost twice as long as 5226 is not desirable. And in any
case the diff isn't usable. And I still think this is being
overly prescriptive in many many places. I also agree with
Benoit that a good set of examples would be more useful,
but maybe that needs to be a separate document now.

- 1.1 (and generally): I'm no so keen on the prescriptive
instructions here - guidance is fine but the should could be
take too seriously in para1.  If the overall draft/RFC is
clear enough for implementers in the end then the job is
done, regardless of where in the RFC the text resides. (And
you later also ask that e.g. rules for upper/lower case are
in IANA sections which conflicts with this.)

- 2, 2nd para: This seems out of place. I doubt most readers
will understand it here. Suggest moving this to later or
deleting it.

- 2.1: I'm not convinced document authors should pay
attention to these groups myself, I've only ever found that
makes finding and naming stuff harder. And I don't think
that we should be making life harder for authors in this
respect, if what's meant is that they ought understand this
before writing a document.

- 3.1: The policy to disallow vanity isn't really IANA's
policy - it should be stated as the IETF's policy.

[Ballot discuss]

This is all updated based on re-reading -15.

(1) 2.3 last para: huh? do we really use and want this? I'd
say delete it. What is the reason for adding this since the
last time this was in IESG review? (Sorry I don't recall it
being discussed, but I assume it was.)

points (2)-(4) cleared.

[Ballot comment]

I didn't check these comments for -16

- Almost twice as long as 5226 is not desirable. And in any
case the diff isn't usable. And I still think this is being
overly prescriptive in many many places. I also agree with
Benoit that a good set of examples would be more useful,
but maybe that needs to be a separate document now.

- 1.1 (and generally): I'm no so keen on the prescriptive
instructions here - guidance is fine but the should could be
take too seriously in para1.  If the overall draft/RFC is
clear enough for implementers in the end then the job is
done, regardless of where in the RFC the text resides. (And
you later also ask that e.g. rules for upper/lower case are
in IANA sections which conflicts with this.)

- 2, 2nd para: This seems out of place. I doubt most readers
will understand it here. Suggest moving this to later or
deleting it.

- 2.1: I'm not convinced document authors should pay
attention to these groups myself, I've only ever found that
makes finding and naming stuff harder. And I don't think
that we should be making life harder for authors in this
respect, if what's meant is that they ought understand this
before writing a document.

- 3.1: The policy to disallow vanity isn't really IANA's
policy - it should be stated as the IETF's policy.

[Ballot comment]
I think this document is an improvement over RFC 5226.

I have several small comments:

In 4.11, numbered item 9: this should also mention BCPs for consistency with other sections.

In 9.5: it might be useful to mention here that Assignee/Owner is also sometimes referred to as "Change Controller".

[Ballot discuss]

This is all updated based on re-reading -15.

(1) 2.3 last para: huh? do we really use and want this? I'd
say delete it. What is the reason for adding this since the
last time this was in IESG review? (Sorry I don't recall it
being discussed, but I assume it was.)

(2) 5.2, last para: would we be better off if we got
agreement from the other streams that the IESG handles all
DEs? I think that's worth thinking about, 'cause it'd be
fine for IRTF I think and afaik that's the only real case at
the moment. And the IRSG haven't had to do such things. And
it'd be simpler I think. But if this is a bad plan, that's
ok I'll clear this bit. This hasn't been discussed that I
recall, but I'd still like to check. (Incidentally the text
in -15 does impose on other streams when it says that they
have to specify how DEs are handled, so the IETF stream is
impinging on others already.)

(3) Section 8 says: "In no case is it reasonable to leave
documentation pointers to the obsoleted document for any
registries or registered items that are still in current
use." We had a nice big discussion about this back a few
years ago and there were two sides to the argument as I
recall.  On what basis can the authors now say that this is
quite so clear? The strong counter argument to this is that
developers do not start from IANA, they start from RFCs.

(4) 9.2: that's news to me, how much of this is there?  I
think having IANA be making policy is not necessarily a good
plan, though I see this was in 5226. Should we change this
now or not? (Just asking but if we think "yes" then we migth
need another LC I guess. If the answer is "no" then this
discuss point goes away.)

[Ballot comment]

- Almost twice as long as 5226 is not desirable. And in any
case the diff isn't usable. And I still think this is being
overly prescriptive in many many places. I also agree with
Benoit that a good set of examples would be more useful,
but maybe that needs to be a separate document now.

- 1.1 (and generally): I'm no so keen on the prescriptive
instructions here - guidance is fine but the should could be
take too seriously in para1.  If the overall draft/RFC is
clear enough for implementers in the end then the job is
done, regardless of where in the RFC the text resides. (And
you later also ask that e.g. rules for upper/lower case are
in IANA sections which conflicts with this.)

- 2, 2nd para: This seems out of place. I doubt most readers
will understand it here. Suggest moving this to later or
deleting it.

- 2.1: I'm not convinced document authors should pay
attention to these groups myself, I've only ever found that
makes finding and naming stuff harder. And I don't think
that we should be making life harder for authors in this
respect, if what's meant is that they ought understand this
before writing a document.

- 3.1: The policy to disallow vanity isn't really IANA's
policy - it should be stated as the IETF's policy.

[Ballot discuss]
I spent quite some time on this one, as I hope this document with ease my live, i.e. reduce my AD load.
Re-reading the entire document, I updated my old DISCUSS/COMMENT.


Section 1.2 "For more information"
  IANA maintains a web page that includes current important information
  from IANA.  Document authors should check that page for additional
  information, beyond what is provided here.

I still don't get how this URL in section 1.2 should/will be used.
- Will it contain important aspects of this BCP, as the paragraph says "current important information"? If yes, why not point to the BCP directly.
- Will it contain some "additional information, beyond what is provided here" ("More information" is the section title). So this BCP is not complete? So we will have a BCP that points to an URL that would contain some additional guidelines (quoting you = "important information"), but we can't tell you right what this is? Basically, what additional type of information do you anticipate on that link, and what is "current" in "current important information"? What if the guidelines on that URL contradict the consensus-base BCP?
I guess I simply don't understand what this URL is for?

[Ballot discuss]
I spent quite some time on this one, as I hope this document with ease my live, i.e. reduce my AD load.
Re-reading the entire document, I updated my old DISCUSS/COMMENT.


Section 1.2 "For more information"
  IANA maintains a web page that includes current important information
  from IANA.  Document authors should check that page for additional
  information, beyond what is provided here.

I still don't get how this URL in section 1.2 should/will be used.
- Will it contain important aspects of this BCP, as the paragraph says "current important information"? If yes, why not point to the BCP directly.
- Will it contain some "additional information, beyond what is provided here" ("More information" is the section title). So this BCP is not complete? So we will have a BCP that points to an URL that would contain some additional guidelines (quoting you = "important information"), but we can't tell you right what this is? Basically, what additional type of information do you anticipate on that link, and what is "current" in "current important information"? What if the guidelines on that URL contradicts the BCP?
I guess I simply don't understand what this URL is for?

[Ballot comment]
From my previous DISCUSS:

    High level summary:
    The two issues that an IANA considerations section writer care about are:
    1. Determining the right procedure (FCFS, Expert Review, etc...). This is relatively easy
    2. What should the IANA considerations section contain? Give us a check list.
        All of us start from examples. This is what we need.
        I see those examples in section 4.X. Good: You can expect IETF draft authors to use those examples, as starting points.
    However, with the current document organization and with the (lack of) RFC 2119 language, it's not too clear to the readers what the checklist is to write an IANA considerations section. Example "change control policy and a change controller". This is missing from the few examples I checked, and it's no clear from the text either if it's a MAY/SHOULD/MUST.

You chose to remove the RFC2119 language entirely. Fine with me. But I'm still missing

I see a good list of "must", starting with "In particular, such instructions must include:" in section 2.2

Btw, editorial:
OLD:

  In particular, such instructions must include:

  The name of the registry
      ...
  Required information for registrations
      ...
  Applicable registration policy
      ...
  Size, format and syntax of registry entries
      ...
  Initial assignments and reservations
      ...
  For example, a document might specify a new registry by including:

NEW:

  In particular, such instructions must include:

  * The name of the registry
      ...
  * Required information for registrations
      ...
  * Applicable registration policy
      ...
  * Size, format and syntax of registry entries
      ...
  * Initial assignments and reservations
      ...
  For example, a document might specify a new registry by including:


Wrt S2.3 (Specifying Change Control for a Registry) is a should, may?
I see:

  It is advised, therefore, that all registries that are created
  clearly specify a change control policy and a change controller. 

It's a pity that I don't have a full list of what I need to check if I want to create a new registry.
This is completely consistent with my previous feedback:
    I'm missing a clear checklist of what I should be doing, as an IANA consideration writer...
    So mixed feelings about this document.

You know, something like, in section 2
NEW:

  Such instructions must include (See Section 2.2) 

  * The name of the registry
      ...
  * Required information for registrations
      ...
  * Applicable registration policy
      ...
  * Size, format and syntax of registry entries
      ...
  * Initial assignments and reservations
      ...
 
  Such instructions should consider:

  * Grouping registry appropriately (See Section 2.1)

  * Change control policy and a change controller (See Section 2.3)


Same remark for "Registering New Values in an Existing Registry" in section 3.

And finally, related to my previous feedback "Example "change control policy and a change controller; This is missing from the few examples I checked", I don't think it has been addressed.

- When I see this:

  For example, a document could contain something like this:

      This registration should be made in the Foobar Operational
      Parameters registry, located at .

  ...

  As an example, the following text could be used to request assignment
  of a DHCPv6 option number:

      IANA is asked to assign an option code value of TBD1 to the DNS
      Recursive Name Server option and an option code value of TBD2 to
      the Domain Search List option from the DHCP option code space
      defined in Section 24.3 of RFC 3315.

I'm wondering: do we speak about the actual text that will be in the RFC-to-be, or instructions for IANA folks (more a like IANA note)? I guess the later because of the tone:  "should be made" and "is asked to assign", right?
I thought the guidelines were to come up with the text that will be published in the final RFC and have IANA note. Am I confused?

- Section 3.2

  In such cases, the document defining the namespace must clearly state
  who is responsible for maintaining and updating a registration.
  Depending on the registry, it may be appropriate to specify one or
  more of:

Isn't it confusing that we're covering the content of section 2.3 again?

- section 4.7
    Can we get a list of examples.

- Section 5.4

  For registrations made from documents on the Standards Track, there
  is often expert review required (by the registration policy) in
  addition to IETF consensus (for approval as a Standards Track RFC).
  In such cases, the review by the designated expert needs to be
  timely, submitted before the IESG evaluates the document.  The IESG
  should generally not hold the document up waiting for late review.
  It is also not intended for the expert review to override IETF
  consensus: the IESG should consider the review in its own evaluation,
  as it would do for other last-call reviews.

The last sentence applies to all registrations, not only Standard Track, right?
Ex: Experimental or Historic.

One the same topic of consensus versus DE review, I see this text:

  Reasons that have been used to deny requests have included these:

  o  Scarcity of code points, where the finite remaining code points
      should be prudently managed, or where a request for a large number
      of code points is made and a single code point is the norm.

I faced the situation where the WG consensus was to allocate code points while the DE disagreed, based on the scarcity argument.
In the end the consensus win.
Just one observation that there are two types of "Reasons that have been used to deny requests have included these"
The ones that consensus would trump (subject to discussion):

      o  Scarcity of code points, where the finite remaining code points
        should be prudently managed, or where a request for a large number
        of code points is made and a single code point is the norm.

      o  The extension would cause problems with existing deployed systems.

... and the other reasons where the DE has all the rights to push back: documentation, conflicts, etc.


Potential improvements:
- I wonder whether a sentence or two regarding the IANA verification at IETF LC (you know, the email such as [IANA #ticket-number] Last Call:  (draft title) to Proposed Standard) would not be welcome. This would stress that a WG LC will trigger a discussion between the authors and IANA regarding the content of the "IANA Considerations" section, to be solved before the draft arrives on the IESG table.
- "Early Allocation Assignment Expirations Report" email, sent by Michelle Cotton on regular basis:

    In accordance with the proposed 2016 SLA, below is the monthly report on the expiration of early allocation assignments in IANA-maintained registries. This message is for your information.  A report will be delivered once per month.

   
    IANA has identified two early allocations that, in accordance with RFC 7120, will expire soon.

While not completely related to "Guidelines for Writing an IANA Considerations Section in RFCs", I wonder if it makes sense to say a few words here. Mixed feelings about that one. It should really be in 7120bis, but not sure we want to update this RFC just for this sentence.

  It is not IANA's responsibility to track the status of allocations,
  their expirations, or when they may be re-allocated.

[Ballot comment]
I find this long, but quite readable. Only a few minor comments:

- 4, numbered list: Does it really make sense to list "IESG Approval" as more strict than "Standards Action?" (considering the latter also implies IESG approval...)

- 4.6: I assume a "specification required" registry could have guidance to the expert above and beyond the "public spec with enough detail part"? If so, a mention of that might be helpful.

- 5.2: "If a designated expert is conflicted..." is a bit ambiguous. An expert could be internally conflicted, have a conflict with others, or have a conflict of interest. I think,  from the remaining context, the last is what you have in mind?

-- I've seen cases of an AD approving a registration when the expert is indisposed or has a conflict of interest. Is that worth a mention? I guess it's sort of the same as appointing oneself as a temporary expert.

[Ballot discuss]

(I just checked my ancient discuss points. It seems to me that
they're still valid, though I may re-word some. That'll be
tomorrow though but in the meantime please consider that
I consider these as still discuss-worthy, and we can start
discussing during the day before the telechat. I didn't
check the comments at all yet.)

There're 5 points here, but they should each be v.  quickly
handled I figure.

(1) 2.2: the MUSTs here are overstated. These are desirable
and not necessary. And we know such MUSTs will not be
honoured and we constantly survive that with nothing bad
happening other than a bit more work for a few folks. I'd say
loose the MUSTs. In general the same tendency is visible
throughout - that is, a tendency to impose a slightly too
high burden on authors via the use of 2119-like language and
I can see that causing trouble later for no good reason
maybe. I think an editing pass to tone that down in general
would be great and would significantly impove the document.
(The discuss will clear if the 2.2 stuff is handled, the rest
are almost all borderline already.)

(2) 5.2, last para: would we be better off if we got
agreement from the other streams that the IESG handles all
DEs? I think that's worth thinking about, 'cause it'd be fine
for IRTF I think and afaik that's the only real case at the
moment. And the IRSG haven't had to do such things. And it'd
be simpler I think. But if this is a bad plan, that's ok I'll
clear this bit.

(3) Section 8 says: "In no case is it reasonable to leave
documentation pointers to the obsoleted document for any
registries or registered items that are still in current
use." We had a nice big discussion about this back a year or
two ago and there were two sides to the argument as I recall.
On what basis can the authors now say that this is quite so
clear? The strong counter argument to this is that developers
do not start from IANA, they start from RFCs.

(4) 9.1: Why do IANA prefer that empty sections be left in
documents? I prefer getting rid of them myself and haven't
heard the logic behind that change. (Or maybe I wasn't paying
attention, in which case apologies:-)

(5) 9.2: that's news to me, how much of this is there?  I
think having IANA be making policy is not necessarily a good
plan, though I see this was in 5226. Should we change this
now or not? (Just asking but if we think "yes" then we migth
need another LC I guess. If the answer is "no" then this
discuss point goes away.)

[Ballot comment]
I do agree with Benoit's Discuss that it would be excellent to have a template example of all the information to be
included - quite clearly.

I did find the document well-written and easy to understand.

Nit:

Section 4, p. 14 "or nor copy" should be "nor copy"

[Ballot discuss]
In Section 2.2, it seems like we could do much better with the URL guidance. I commented on this last time but the same problem still exists in this version. Right now the guidance amounts to: "include a URL, make sure it's a permalink, but we can't tell you how to find or construct a permalink reliably, so ask IANA, but we don't tell you how to ask." If we're far enough away from having a standard way to find or construct permalinks that we can't say anything more specific about how authors might figure out what to include, then I think it's preferable to just tell people to include a URL for the registry in question and note that IANA will confirm whether to replace it with a permalink as part of its document processing. Asking authors to have an additional back-and-forth with IANA because we don't have an easy way for authors to identify permalinks seems like a waste of time for both sides.

[Ballot comment]
I re-read this document since it has been a long while since the last time it was on a telechat.

- I still find this document to be long and to have superfluous text or multiple instances where the same point is made repeatedly. E.g., Section 4.8 mentions twice in two paragraphs that documents will be last called, the last sentence of 4.11 is obvious enough to be omitted, the explanation of what a bis document is in Section 8 is unnecessary, Section 11 is superfluous, etc. It would be nice if someone could do a full edit pass and pare this doc down to its essence.

- I find the organization of Section 2 confusing. I agree with Benoit's old DISCUSS still -- I think the main thing authors are looking for here is the list of elements they need to include when creating a new registry. But Section 2 does not contain a single list. There is a brief list in the first sentence of the section, and then a longer list in 2.2, but then 2.3 and 3.2 talk about other items which are not included in the list in 2.2. I think this section would be clearer if it included a single list of the expected elements rather than multiple separate incomplete lists.

- Section 2.1: The table and the two paragraphs that follow it are unnecessary. Anyone reading this document can click the link and see exactly what is described here.

- Section 4.4: Is there any protocol parameter registry that still requires a postal address as a practical matter?

- Section 4.4, 4.5: The text about change control is duplicative of 2.3 and could be confusing, since 2.3 says to always specify a change controller and here it's being called out specifically for particular kinds of registries.

- Section 4.11: In Section 4.5 authors are told to include info about required documentation, review criteria, guidance, reasons for rejecting a request, etc. whenever choosing Expert Review as the policy. Does RFC 3575 really give more detail than what would normally be expected when this policy is chosen? To me it seems like it gives a bit more process detail than usual, but not more criteria detail, and therefore calling it out seems to give the wrong impression about what authors should normally do when choosing Expert Review.

[Ballot comment]
A few comments for clarification:

1) I find the following sentence on private or experimental use slightly confusing:
"IANA does not record assignments from registries or ranges with this policy"
I would say that these values ARE assigned, as private or experimental by IANA.

2) Is "Hierarchical Allocation" (section 4.3) really an own policy given that IANA only registers "top-level" namespace and usually does not take track of the subnamespace handling anymore?

3) Double-checking: Does "RFC Required" mean that no expert review is needed? IS would be sufficient? Do we actually have this use case (given there are also no examples given here)?

[Ballot comment]
I think this document is an improvement over RFC 5226.

I have several small comments:

In 2.3: the last sentence of the first para is just rewording a previous sentence in the same para?

In 2.3: I've seen cases when a non-IETF stream document asks for IESG to be change controller. I think this is an Ok case as well. Should this be mentioned?

In 4.11, numbered item 9: this should also mention BCPs for consistency with other sections.

In 9.5: it might be useful to mention here that Assignee/Owner is also sometimes referred to as "Change Controller".

(Via drafts-lastcall-comment@iana.org): IESG/Authors/WG Chairs:

IANA has reviewed draft-leiba-cotton-iana-5226bis-12.txt, which is currently in Last Call, and has the following comments:

We understand that this document doesn't require any IANA actions.

While it's often helpful for a document's IANA Considerations section to remain in place upon publication even if there are no actions, if the authors strongly prefer to remove it, IANA does not object.

If this assessment is not accurate, please respond as soon as possible.

Thank you,

Sabrina Tanamal
IANA Specialist
ICANN

The following Last Call announcement was sent out:

From: The IESG
To: "IETF-Announce"
CC: draft-leiba-cotton-iana-5226bis@ietf.org, tony@att.com, terry.manderson@icann.org
Reply-To: ietf@ietf.org
Sender:
Subject: Last Call:  (Guidelines for Writing an IANA Considerations Section in RFCs) to Best Current Practice


The IESG has received a request from an individual submitter to consider
the following document:
- 'Guidelines for Writing an IANA Considerations Section in RFCs'
  as Best Current Practice

The IESG plans to make a decision in the next few weeks, and solicits
final comments on this action. Please send substantive comments to the
ietf@ietf.org mailing lists by 2016-05-17. Exceptionally, comments may be
sent to iesg@ietf.org instead. In either case, please retain the
beginning of the Subject line to allow automated sorting.

Abstract


  Many protocols make use of points of extensibility that use constants
  to identify various protocol parameters.  To ensure that the values
  used in these fields do not have conflicting uses, and to promote
  interoperability, their allocation is often coordinated by a central
  record keeper.  For IETF protocols, that role is filled by the
  Internet Assigned Numbers Authority (IANA).

  To make assignments in a given registry prudently, IANA needs
  guidance describing the conditions under which new values should be
  assigned, as well as when and how modifications to existing values
  can be made.  This document defines a framework for the documentation
  of these guidelines by specification authors, in order to assure that
  the guidance given to IANA is clear and addresses the various issues
  that are likely in the operation of a registry.

  This is the third edition of this document; it obsoletes RFC 5226.




The file can be obtained via
https://datatracker.ietf.org/doc/draft-leiba-cotton-iana-5226bis/

IESG discussion can be tracked via
https://datatracker.ietf.org/doc/draft-leiba-cotton-iana-5226bis/ballot/


No IPR declarations have been submitted directly on this I-D.

This document has had some substantive changes, and has been with the IESG for an extended duration. I would like the community to take another look.

[Ballot comment]
This is a very helpful document.  Thanks for doing it.  I did not find it overly wordy--it was a clear and easy read, despite its length.

In 2.3.1:

  Examples of situations that might merit RFC Required, IETF Review, or
  Standards Action include the following:

  o  When a resource is limited, such as bits in a byte (or in two
      bytes, or four), or numbers in a limited range.  In these cases,
      allowing registrations that haven't been carefully reviewed and
      agreed by community consensus could too quickly deplete the
      allowable values.

  o  When thorough community review is necessary to avoid extending or
      modifying the protocol in ways that could be damaging.  One
      example is in defining new command codes, as opposed to options
      that use existing command codes: the former might require a strict
      policy, where a more relaxed policy could be adequate for the
      latter.  Another example is in defining protocol elements that
      change the semantics of existing operations.

This doesn't actually make sense: "RFC Required" does not really imply that there has been thorough community review or consensus.  I think you want RFC Required when you want there to be a document available that explains what a given code point is used for, and/or what its related format is.  So I would encourage you to explain "RFC required" separately, and perhaps use my explanation for why you would want that as a registration policy, if you agree that I've described it correctly.

In 4.10, it's perhaps worth noting that "IESG approval" is essentially always a possibility for an IANA allocation that is under IETF control.  That being the case, it might be worth saying why this is different.  (I think the difference is that this is an anticipated (as opposed to unanticipated) need, and therefore doesn't imply the need to change the registration policy.)

In 5.2, it would be nice if it were required that the expert explain the decision and that the IANA make a record of that explanation that would be available if someone had a question about it.  I think this is sort of happening already in the IANA tracker, as long as the designated expert explains the decision, but maybe that should be made explicit?

[Ballot discuss]
I initially wanted to go for "no-record" and wait for the discussion during the IESG telechat to give my final ballot.
I was convinced it was not the right approach.
So here is my DISCUSS, expressing that I want to discuss this document with the IESG.

High level summary:
The two issues that an IANA considerations section writer care about are:
1. Determining the right procedure (FCFS, Expert Review, etc...). This is relatively easy
2. What should the IANA considerations section contain? Give us a check list.
    All of us start from examples. This is what we need.
    I see those examples in section 4.X. Good: You can expect IETF draft authors to use those examples, as starting points.
However, with the current document organization and with the (lack of) RFC 2119 language, it's not too clear to the readers what the checklist is to write an IANA considerations section. Example "change control policy and a change controller". This is missing from the few examples I checked, and it's no clear from the text either if it's a MAY/SHOULD/MUST.
So mixed feelings about this document. Not sure it's well organized for the intended audience: "Guidelines for Writing an IANA Considerations Section in RFCs ".

[Ballot comment]


- Section 1.2

  IANA maintains a web page that includes current important information
  from IANA.  Document authors should check that page for additional
  information, beyond what is provided here.

      .


This points to  "This is a placeholder for a future document."

- Section 2.1
When I see

    Unfortunately, we have been inconsistent in how we refer to these
      entities.  The group names, as they are referred to here, have been
      variously called "protocol category groups", "groups", "top-level
      registries", or just "registries".  The registries under them have
      been called "registries" or "sub-registries".  And when new
      registries are created, the documents that define them often don't
      specify the grouping at all, but only name the new registry.  This
      results in questions from IANA and delays in processing, or, worse,
      in related registries that should have been grouped together, but
      that are instead scattered about and hard to find and correlate.

What is the guideline for the readers?

- RFC 2119
I don't believe that they are used in a consistent way.
One on hand, you use RFC 2119 keyword.

  Documents that create a new namespace (or modify the definition of an
  existing space) and that expect IANA to play a role in maintaining
  that space (serving as a repository for registered values) MUST
  provide clear instructions on details of the namespace, either in the
  IANA Considerations section, or referenced from it.

On the other hand, it's unspecified (just three examples, there are certainly more)
Section 2.3.2

  This can be documented in the IANA Considerations section when the
  registry is created:

Section 2.3.3

  It is advised, therefore, that all registries that are created
  clearly specify a change control policy and a change controller.

What I need to understand, as someone writing a IANA considerations section.
MAY, SHOULD or MUST I mention "change control policy and a change controller"?
It's unclear to me.

Section 3.1

  Such documents should clearly identify the namespace into which each
  value is to be registered.

should or SHOULD? Or actually MUST.
In the end, I wonder about the value of RFC 2119 keywords...

- one more inconsistency:
Section 2.3.3

  It is advised, therefore, that all registries that are created
  clearly specify a change control policy and a change controller.

Section 3.2

  In such cases, the document defining the namespace must clearly state
  who is responsible for maintaining and updating a registration.



- Section 3.1

  There is no need to mention what the assignment policy is when making
  new assignments in existing registries, as that should be clear from
  the references.

Let me take an example, to illustrate my point: draft-murdock-nato-nid-02, on this telechat

    6. IANA Considerations


      This document defines a URN NID registration of "nato", which is
      requested to be entered into the IANA registry "Uniform Resource
      Names (URN) Namespaces".  The registration template is given in
      section 2.


    While it's not really a complex task, I have to search IANA for "Uniform Resource Names (URN) Namespaces" in order to find the [RFC2141][RFC3406] references and find that "IETF consensus.
    But why not add it directly in the IANA considerations section, to ease the reviewer lives?

- I see an inconsistency in section 3.1

  When referring to an existing registry, providing a URL to precisely
  identify the registry is helpful.  See Section 2.2 for details on
  specifying the correct URL.

  For example, a document could contain something like this:

      This registration should be made in the Foobar Operational
      Parameters registry, located at .

The example in section 2.2 mentions "to be removed"

    X. IANA Considerations

      This document defines a new DHCP option, entitled "FooBar" (see
      Section y), assigned a value of TBD1 from the DHCP Option space
      [to be removed upon publication:
      http://www.iana.org/assignments/bootp-dhcp-parameters]
      [RFC2132] [RFC2939]:

Note: coming back on the MUST, SHOULD, MAY

  When referring to an existing registry, providing a URL to precisely
  identify the registry is helpful.  See Section 2.2 for details on
  specifying the correct URL.

"is helpful" is the type of terms that is not that helpful to the readers. I want to write an IANA considerations section, and I need clear guidelines, almost like a checklist.
Same remark for

  It is also helpful for
  this table to be in the same format as it appears or will appear on
  the IANA web site.  For example:


  Value    Description          Reference
  --------  -------------------  ---------
  TBD1      Foobar              [[this RFC]]


Note that the example, 2 paragraphs below, doesn't contain the table???

  As an example, the following text could be used to request assignment
  of a DHCPv6 option number:

      IANA has assigned an option code value of TBD1 to the DNS
      Recursive Name Server option and an option code value of TBD2 to
      the Domain Search List option from the DHCP option code space
      defined in Section 24.3 of RFC 3315.

I'm missing a clear checklist of what I should be doing, as an IANA consideration writer...

[Ballot comment]
I agree with Adrian and others, that this document is important, but could be shorter.  I'd change to a Yes ballot with my questions getting a response and the draft getting a bit shorter (condense sections 2.3 & 4 - Alissa, and highlighting 4&6 - Adrian).

Questions:

Section 2.3.x Specification Required - an example of a low bar would be helpful…
        Section 2.3.1 says "Significant stable public documentation sufficient for
        interoperability."

    Is an email to an IETF list adequate? If so, can we list that as an example?
    I have had this questioned a few times recently (even from a former AD)
    and a few other ADs said an email on an IETF list would suffice because
    there is a stable way to point to it in the archives.  If this is the case,
    it would be great to document that so it is clear on the bar.  We don't want
    to have drafts coming through that are not necessary.  This should probably
    go in section 4.6 and I could see where this might be adequate for some
    additions to registries. It would be easy to argue that a URL to an IETF
    list email would be more stable than a document posted on a web site.

Section 4.4
There should probably be some privacy considerations listed since contact information is provided and maintained (contact person field and change controller).  Perhaps something like the following (I'm one to alternate options):

"When submitting contact information, the use of aliases or purpose specific business email addresses may be considered to protect the privacy of individuals personal contact information."


Security Considerations
Adrian & Alissa raised questions on security review and registration policies.  In my draft reviews, I've kept those points separate.  If there were security considerations specific to a requested registry addition over and above the considerations of the draft establishing the registry, then I'd want those documented within the specification required document text (whatever that stable document is).


Reduction of text suggestions intended to be helpful:

Section 1.1
See Alissa commented on reducing this one as well, I agree.

Section 2.1
The second to last paragraph might be safely cut as well.  It looks like Alissa recommended the one before this and I think Benoit agrees on delating the one too from his comments.  It may be safe to cut both.

[Ballot comment]
Section 2:
"consider delegating the namespace"
What do you mean by "delegating" here?  Having some organization other than IANA run it?  "Before using IANA, please consider not using IANA"?  Especially in light of the DNS example, it seems like this is not really what you mean.  "consider structuring the namespace in such a way that allocations can be made without central coordination."

Section 2.2.
"See Section y.1"
Isn't this a counterexample?  That's not what you would actually put in the registry; you would put "RFC [XXXX], Section y.1"

[Ballot discuss]
2.1/2.2 - You rightly point out in 2.1 that the terminology has been inconsistent in the past. But then you go ahead in 2.2 and use the two most confusing terms that you could use ("registry" for the grouping and "sub-registry" for the thing that contains the namespace). Please come up with terminology for this version of the document and stick to it. I would very much prefer "Category" (or "Grouping") for the grouping and "Registry" for the thing that contains the namespace. The documentation requirement should be for the Registry name, and, if desired, the Category (or Grouping) into which the Registry goes. The grouping can be identified by name or (if it already exists) by URL. If you insist on using the terms "registry" and "sub-registry" (and I implore you not to), please at least define those terms in terms of category, grouping, and namespace. In any event, please do not update this document without fixing the problem.

2.2 - The size/format section makes it confusing as to whether you're defining technical *protocol* requirements (which don't belong in the registry definition) or requirements for the registry itself (i.e., how things are displayed or stored by IANA). I particularly don't like giving UTF8 as an example. If the thing in the registry is a text string, then "Zürich" is a fine entry, whether it is stored in the registry at IANA with the second character as U+00FC or U+0075 U+0308 (however encoded); the registry should point back elsewhere in the document to define the encoding requirements or the normalizations that might be used. However, if the thing in the registry is a specific UTF8-encoded octet-string, then what should appear in the registry should either contain "0xC3 0xBC" or it should contain "0x75 0xCC 0x88" and not appear as "ü". The paragraph should make that clear.

In the example, I'm not clear on what "under the FooBar option" means. That sounds like there is a Category called "FooBar Options" somewhere, but I don't think that's what you mean.

[Ballot comment]
Overall: I think this document could use a good edit pass to remove redundant information and put things in the correct order. Lots of information is scattered because it is repeated in several places.

I also agree that the 2119 language in here is not useful.

Specifics:

1 - I agree that you should strike the last sentence of the first paragraph.

1.1 - I suggest a small insertion:

OLD
  But if it's necessary to include a longer technical explanation of
  the purpose and use of the item,
NEW
  But if it's necessary to include a normative definition or longer
  technical explanation of the purpose and use of the item,
END

2.3/2.3.* - I agree with Adrian and Alissa's concerns. This could really be edited down quite a bit and combined with section 4, removing lots of duplication throughout. Giving the menu of policies *first* and then describing how to use them seems like a good plan. The second-to-last and third-to-last paragraphs of 2.3 seem unnecessary.

4.8 - Does an Info/Exp RFC without the consensus box checked count for IETF Review?

4.9 - How about BCPs?

4.10 - The reference to RFC 2434 is odd.

5.4 - I'm suspicious about this section. I suspect it was written when it was thought that experts would be reviewing IETF Review documents. (Cf. discussion of the IESG and the "token held by the responsible Area Director".) In 2.3.2, it explains that this scenario really shouldn't be coming up, because experts need not (ought not?) be on the hook to review IETF Review documents. I'm not convinced these two section jive with each other.

[Ballot discuss]

There're 5 points here, but they should each be v.  quickly
handled I figure.

(1) 2.2: the MUSTs here are overstated. These are desirable
and not necessary. And we know such MUSTs will not be
honoured and we constantly survive that with nothing bad
happening other than a bit more work for a few folks. I'd say
loose the MUSTs. In general the same tendency is visible
throughout - that is, a tendency to impose a slightly too
high burden on authors via the use of 2119-like language and
I can see that causing trouble later for no good reason
maybe. I think an editing pass to tone that down in general
would be great and would significantly impove the document.
(The discuss will clear if the 2.2 stuff is handled, the rest
are almost all borderline already.)

(2) 5.2, last para: would we be better off if we got
agreement from the other streams that the IESG handles all
DEs? I think that's worth thinking about, 'cause it'd be fine
for IRTF I think and afaik that's the only real case at the
moment. And the IRSG haven't had to do such things. And it'd
be simpler I think. But if this is a bad plan, that's ok I'll
clear this bit.

(3) Section 8 says: "In no case is it reasonable to leave
documentation pointers to the obsoleted document for any
registries or registered items that are still in current
use." We had a nice big discussion about this back a year or
two ago and there were two sides to the argument as I recall.
On what basis can the authors now say that this is quite so
clear? The strong counter argument to this is that developers
do not start from IANA, they start from RFCs.

(4) 9.1: Why do IANA prefer that empty sections be left in
documents? I prefer getting rid of them myself and haven't
heard the logic behind that change. (Or maybe I wasn't paying
attention, in which case apologies:-)

(5) 9.2: that's news to me, how much of this is there?  I
think having IANA be making policy is not necessarily a good
plan, though I see this was in 5226. Should we change this
now or not? (Just asking but if we think "yes" then we migth
need another LC I guess. If the answer is "no" then this
discuss point goes away.)

[Ballot comment]

- Almost twice as long as 5226 is not desirable. And in any
case the diff isn't usable.

- Abstract and intro (at least): I don't think of IANA as a
"central authority" but more like the bookkeeper - the
authority resides with the IESG. s/authority/something else/
would be better. Funnily enough, that was almost a discuss,
so I've obviously been reading too much ianaplan mail;-)

- 1.1: I'm no so keen on the instructions here - guidance is
fine but the should could be take too seriously in para1.

- 1.2: saying that URL goes to a placeholder at the time of
writing could be good.

- 2: What does "delegating the namespace" mean? I don't get
it anyway. If you'r recommending it, you need to explain it
better. And DNS names are not a good example for the average
protocol designer.

- 2.1: I'm not convinced document authors should pay
attention to these groups myself, I've only ever found that
makes finding and naming stuff harder. And I don't think that
we should be making life harder for authors in this respect,
if what's meant is that they ought understand this before
writing a document.

- 2.2: Why is the URL not the permanent link to the registry?
Seems like it'd be better if it were.

- 2.3.1, 4th last para: Huh? This seems to be telling the
IESG to do a thing, but I'm not clear what.

- 2.3.1: last para is unclear

- 2.3.2: I find this unclear, and doesn't IETF consensus
trump anything else anyway?

- 2.3.3: Is the iesg the backstop in all these non IETF
cases? Say if some other SDO goes away or whatever.

- 3.1: here you recommend including the URL, but earlier you
did not, consistent would be better.

- 3.1: you go from saying its "helpful" to include the table
in the draft to saying that it should be done (3rd last
para). "helpful" is much better, "should" is overreach.

- 4.6: this has a lowercase must where you might prefer a
MUST and where that MUST would be ok (3rd line)

- Section 6 has a much more sensible use of private use and
experimental - why couldn't those be gotten rid of from 4.x?

- 7, 1st bullet: the "that document" is ambiguous

- 7, last bullet: the "and shouldn't" here is a bad idea,
there will be many times when having that text in the IANA
considerations section is just fine

- 9.1: Another gratuituous must: "This statement, or an
equivalent, must only be inserted..." That's not needed.

- 9.6: does this apply to all streams?

- I see Barry responded to the secdir review [1] but it
wasn't clear to me if that discussion was really over or not.
Might be no harm to check but I didn't see anything blocking
there.

  [1] https://www.ietf.org/mail-archive/web/secdir/current/msg05198.html

[Ballot comment]
High level summary:
The two issues that an IANA considerations section writer care about are:
1. Determining the right procedure (FCFS, Expert Review, etc...). This is relatively easy
2. What should the IANA considerations section contain? Give us a check list.
    All of us start from examples. This is what we need.
    I see those examples in section 4.X. Good: You can expect IETF draft authors to use those examples, as starting points.
However, with the current document organization and with the (lack of) RFC 2119 language, it's not too clear to the readers what the checklist is to write an IANA considerations section. Example "change control policy and a change controller". This is missing from the few examples I checked, and it's no clear from the text either if it's a MAY/SHOULD/MUST.
So mixed feelings about this document. Not sure it's well organized for the intended audience: "Guidelines for Writing an IANA Considerations Section in RFCs ". I've been debating with myself for some time now how to ballot this document. I'll go for no-record for now.


- Section 1.2

  IANA maintains a web page that includes current important information
  from IANA.  Document authors should check that page for additional
  information, beyond what is provided here.

      .


This points to  "This is a placeholder for a future document."

- Section 2.1
When I see

    Unfortunately, we have been inconsistent in how we refer to these
      entities.  The group names, as they are referred to here, have been
      variously called "protocol category groups", "groups", "top-level
      registries", or just "registries".  The registries under them have
      been called "registries" or "sub-registries".  And when new
      registries are created, the documents that define them often don't
      specify the grouping at all, but only name the new registry.  This
      results in questions from IANA and delays in processing, or, worse,
      in related registries that should have been grouped together, but
      that are instead scattered about and hard to find and correlate.

What is the guideline for the readers?

- RFC 2119
I don't believe that they are used in a consistent way.
One on hand, you use RFC 2119 keyword.

  Documents that create a new namespace (or modify the definition of an
  existing space) and that expect IANA to play a role in maintaining
  that space (serving as a repository for registered values) MUST
  provide clear instructions on details of the namespace, either in the
  IANA Considerations section, or referenced from it.

On the other hand, it's unspecified (just three examples, there are certainly more)
Section 2.3.2

  This can be documented in the IANA Considerations section when the
  registry is created:

Section 2.3.3

  It is advised, therefore, that all registries that are created
  clearly specify a change control policy and a change controller.

What I need to understand, as someone writing a IANA considerations section.
MAY, SHOULD or MUST I mention "change control policy and a change controller"?
It's unclear to me.

Section 3.1

  Such documents should clearly identify the namespace into which each
  value is to be registered.

should or SHOULD? Or actually MUST.
In the end, I wonder about the value of RFC 2119 keywords...

- one more inconsistency:
Section 2.3.3

  It is advised, therefore, that all registries that are created
  clearly specify a change control policy and a change controller.

Section 3.2

  In such cases, the document defining the namespace must clearly state
  who is responsible for maintaining and updating a registration.



- Section 3.1

  There is no need to mention what the assignment policy is when making
  new assignments in existing registries, as that should be clear from
  the references.

Let me take an example, to illustrate my point: draft-murdock-nato-nid-02, on this telechat

    6. IANA Considerations


      This document defines a URN NID registration of "nato", which is
      requested to be entered into the IANA registry "Uniform Resource
      Names (URN) Namespaces".  The registration template is given in
      section 2.


    While it's not really a complex task, I have to search IANA for "Uniform Resource Names (URN) Namespaces" in order to find the [RFC2141][RFC3406] references and find that "IETF consensus.
    But why not add it directly in the IANA considerations section, to ease the reviewer lives?

- I see an inconsistency in section 3.1

  When referring to an existing registry, providing a URL to precisely
  identify the registry is helpful.  See Section 2.2 for details on
  specifying the correct URL.

  For example, a document could contain something like this:

      This registration should be made in the Foobar Operational
      Parameters registry, located at .

The example in section 2.2 mentions "to be removed"

    X. IANA Considerations

      This document defines a new DHCP option, entitled "FooBar" (see
      Section y), assigned a value of TBD1 from the DHCP Option space
      [to be removed upon publication:
      http://www.iana.org/assignments/bootp-dhcp-parameters]
      [RFC2132] [RFC2939]:

Note: coming back on the MUST, SHOULD, MAY

  When referring to an existing registry, providing a URL to precisely
  identify the registry is helpful.  See Section 2.2 for details on
  specifying the correct URL.

"is helpful" is the type of terms that is not that helpful to the readers. I want to write an IANA considerations section, and I need clear guidelines, almost like a checklist.
Same remark for

  It is also helpful for
  this table to be in the same format as it appears or will appear on
  the IANA web site.  For example:


  Value    Description          Reference
  --------  -------------------  ---------
  TBD1      Foobar              [[this RFC]]


Note that the example, 2 paragraphs below, doesn't contain the table???

  As an example, the following text could be used to request assignment
  of a DHCPv6 option number:

      IANA has assigned an option code value of TBD1 to the DNS
      Recursive Name Server option and an option code value of TBD2 to
      the Domain Search List option from the DHCP option code space
      defined in Section 24.3 of RFC 3315.

I'm missing a clear checklist of what I should be doing, as an IANA consideration writer...

[Ballot comment]
= General =
I agree with Adrian that this document seems a lot longer/wordier than it needs to be. Text that seems like it could easily be deleted without losing substantive value:

2nd paragraph of 1.1
1st paragraph after the list of protocol registry groups in 2.1
Paragraphs 1-4 of 5.1
Most of the text in 9.1
Section 11

We might also want to think about a posting a short page on ietf.org (if one doesn't already exist) that contains the bits that are salient to most document authors -- perhaps a table of required elements to create a new registry or update one, a bit about sub-registries, and the listing of well-known registration policies -- since I doubt too many people will read this or have read 5226.

= Abstract =
s/This is the third edition/This is the third edition of this document/

= Section 1=
"IANA services are
  currently provided by the Internet Corporation for Assigned Names and
  Numbers (ICANN)."

Not to poke a hornet's nest, but do you really want to have to update this document if the only thing that changes in the future is this statement? I don't think the statement is particularly necessary.

= Section 2.1 =
"It's important to start with a word on the IANA registry structure."

This is superfluous and could be deleted.

= Section 2.2 =
Agree with Adrian's comment about "Required information for registrations" -- I don't get it.

"IANA intends to include
      the permalink for each registry in the registry header.  Until
      that is done, IANA can answer questions about the correct URLs to
      use."

I'm confused about a number of points here. What is a "registry header"? This text makes it sound like IANA has a project underway to put permalinks in all of the registry pages -- is that what this is trying to say? Regardless, the directive to the document author here seems very strange. The point of this section seems to be that as the author is drawing up her IANA considerations section, she should include a permalink to the registry in question so that it's clear to IANA which registry she is referring to. But if she can't find the permalink, she's supposed to go ask IANA what the link is? Doesn't that defeat the purpose of including the link for clarity for IANA in the first place?

= Section 2.3 =
It seems quite strange to me that Section 2.3 is separated from Section 4. It seems to introduce some duplication into the document, since the list of well-known policies is discussed twice, and lots of forward and backward references. I would suggest having all of the information about registration policies, both in general and specifically the well-known ones, in one section.

= Section 2.3.1 =
"The description in Section 4.10 of "IESG Approval" suggests that the
  IESG "can (and should) reject a request if another path for
  registration is available that is more appropriate and there is no
  compelling reason not to use that path."  The IESG should give
  similar consideration to any registration policy more stringent than
  Expert Review or Specification Required, asking for justification and
  ensuring that more relaxed policies have been considered, and the
  strict policy is the right one."

The mixing of two different IESG functions here is really confusing. The first part appears to be talking about the situation in which the IESG is asked to approve a registration. The second one appears to be talking about the situation in which the IESG is asked to approve a document that asks IANA to create a new registry. Is that right? This would have made a lot more sense to me if it simply said, "When reviewing a document that asks IANA to create a new registry or change a registration policy to any policy more stringent than Expert Review or Specification Required, the IESG should ask for justification to ensure that more relaxed policies have been considered and that the strict policy is the right one."

= Section 2.3.3 =
s/desired/desirable/

= Section 2.4 =
"Remember to
  check this, and give clear instructions to IANA."
 
This is superfluous and could be deleted.

"Such documents are normally processed with the same document status
  as the document that created the registry, or as Best Current
  Practices (BCPs) [RFC2026]."

I know we've talked about this before, but it seems really odd to me to encourage people to write BCPs in order to add a column to an IANA registry.

= Section 4.5 =
This section should include a specific forward reference to 5.2.1 about how experts are chosen. This confuses a lot of people.

= Section 4.6 =
It might be worth including a few words in this section about whether review criteria (beyond evaluating the given spec for interoperability) need to be provided to the expert, since that is explicitly mentioned in Section 4.5.

= Section 4.8 =
Seems like this text from 4.7 should also be included here, if true (I think people get confused about this):

"Unless otherwise specified, any
  type of RFC is sufficient (currently Standards Track, BCP,
  Informational, Experimental, or Historic)."

= Section 4.10 =
"The IESG can (and should) reject a request if another path for
      registration is available that is more appropriate and there is no
      compelling reason not to use that path."

I don't understand the scenario here. Is this for when there are multiple registration policies and IESG Approval is one of them? "Another path" seems vague.

= Section 5.2 =
"It has proven useful to have multiple designated experts for some
  registries.  Sometimes those experts work together in evaluating a
  request, while in other cases additional experts serve as backups.
  In cases of disagreement among those experts, it is the
  responsibility of those experts to make a single clear recommendation
  to IANA.  It is not appropriate for IANA to resolve disputes among
  experts.  In extreme situations, such as deadlock, the designating
  body may need to step in to resolve the problem."

This paragraph needs to be reconciled with the paragraphs above it about having a pool of experts with a chair -- the information here seems to be in conflict with that description.

"Documents in other streams may
  use a registration policy that requires a designated expert only if
  those streams (or those documents) specify how designated experts are
  appointed and managed."

This seems to leave the reader hanging -- shouldn't we say whether the other streams have defined a process here and give references if so, are explain that no references exist if not?

= Section 5.3 =
"Possible reasons to deny a request include these:"

I think the preamble here needs to make clear that the criteria provided are for historical cases where guidance has not been provided to the expert. I don't think the criteria listed here should be interpreted as otherwise superseding the guidance provided to an expert through IETF consensus.

= Section 12 =
Not sure if I missed it, but I didn't see in this section or any other part of the document a discussion of how security considerations can factor into the selection of a registration policy. It seems to be somewhat common practice to consider the need for broad security review as a reason for specifying a stricter registration policy as opposed to a more lenient one. Perhaps the sec ADs have more to say about this, but this document seems like a reasonable place to discuss the relationship between security review and registration policies.

[Ballot comment]
I am conflicted as to what ballot position to enter! In the end I
selected "Yes" because I think that publication as an RFC outweighs my
concerns about the document.

However, I present a list of editorial considerations.

I spent some time in Honolulu asking established IETF participants why
they find writing IANA considerations sections so hard. The answer I got
was that 5226 was too much to plough through and so they just guessed.
That is a problem we need to address somehow.

RFC 5226 is 27 pages long. This I-D is 37 pages long. I don't think this
is helping. Perhaps the solution is to bring out the key sections of the
document to be easily discovered (currently sections 4 and 6) and
presented as the core text.

I know this isn't a helpful comment at this stage, and I know you aren't
likely to restart your work with the intent of deleting swathes of text
so just take this as me whining. (But I really found most of sections 2
and 5 added unnecessary description and was a bit jumbled. I also
thought section 2 errs on the side of making access to code points easy
where interop and protocol-bastardisation are a risk - but I have been
burned.)

---

Section 1.2

I looked at http://iana.org/help/protocol-registration
It's an empty placeholder. I recommend against referencing it unless
the IANA is making a pedge to fill the page before publication of the
RFC.

---

I really think that the use of 2119 langauge is unnecessary.
Furthermore, it is used incosistently with some elements of the
procedures described in lower case normal English.

---

Section 2

Is it necessary to indicate the plural(s) in this way?
English allows a single instance as a special case of a plural.

---

Section 2

  listing an initial set of assignments (if appropriate)

I think that is s/appropriate/applicable/

---

Section 2 has

  Before defining a registry, however, consider delegating the
  namespace in some manner.

Pedantically I think this is s/Before/When/ as the Hierarchical
assignment policy is just another policy in the list.

Carrying on in the section you have

  In particular, not all namespaces require a registry; in some cases,
  assignments can be made independently and with no further (central)
  coordination.  In the Domain Name System, for example, IANA only
  deals with assignments at the higher levels, while subdomains are
  administered by the organization to which the space has been
  delegated.  When a namespace is delegated in this manner, the scope
  of IANA is limited to the parts of the namespace where IANA has
  authority.

This is slightly confusing firstly because namespaces that don't require
a registry don't fall into scope of this document, and also because the
example given, there is a registry with Hierarchical assignment policy.

---

Section 2.1 is perfectly correct but the choice of "Hierarchical" is
unfortunate coming immediately after a section on that discussed
delegation which (although not mentioned) is through the Hiearchical
assignment policy.

Maybe just "Sturcture of Registries" or "Organisation of Registries"

---

In Section 2.1

  In the example section above, there are two registries
  related to the ADSP protocol, and they are both placed in the "ADSP
  Parameters" group.

  Within the "ADSP Parameters" group are two registries: "ADSP Outbound
  Signing Practices" and "ADSP Specification Tags".

There seems to be some repetition.

---

Section 2.1

  And when new
  registries are created, the documents that define them often don't
  specify the grouping at all, but only name the new registry.  This
  results in questions from IANA and delays in processing, or, worse,
  in related registries that should have been grouped together, but
  that are instead scattered about and hard to find and correlate.

Wouldn't it be better to fold this into the subsequent paragraph to
give advice and guidance on how to do things right rather than
commentary on how things are done wrong?

---

Section 2.2

I found

  Required information for registrations

      This information may include the need to document relevant
      Security Considerations, if any.

more confusing than helpful. I looked for more details on this
information but didn't immediately find anything. Can you include a
forward pointer to the relevant section?

---

Section 2.2

  Applicable review process

      The review process that will apply to all future requests for
      registration.  See Section 2.3.

Is this intended to be the assignment or registration policy?
(Although in section 2.3 you call it a "Regsitry Policy".)

---

Shouldn't 2.3 start with two lines saying what an Registry Policy is?

---

Section 2.3

  Even when the space is essentially unlimited, however, it is usually
  desirable to have at least a minimal review prior to assignment in
  order to:

s/however, it is/it is still/

But I would quibble with "usually" since that flies in the face of FCFS.
And, indeed, subsequent text says
  When the namespace is essentially unlimited and there are no
  potential interoperability or security issues, assigned numbers can
  usually be given out to anyone without any subjective review.
which is the same "essentially unlimited".

---

Missing from, but implicit in the first two paragraphs of Section 2.3.1
is that ayone can make up any registration policy they like and that no-
one has grounds to object. If that is intended it should be said
(elsewhere you also only recommend - not mandate - the use of one of the
defined policies).

---

Section 2.3.2

In the case of multiple registration policies that we see in the
registries today, there is typically poor or no guidance about the use
of the competing policies. Your text wisely says "Guidance should be
provided about when each policy is appropriate", but the example is a
bit woolly in that it only says *a* circumstance under which one of the
two policies should be used. It would help, I think, if the example
could be tighter and so give a better template for people defining
registries. For example,

      IANA is asked to create the registry "Fruit Access Flags" as a
      sub-registry of "Fruit Parameters".  New registrations will be
      permitted through either the IETF Review policy or the
      Specification Required policy [BCP26].  The latter should be used
      only for registrations requested by SDOs outside the IETF: all
      other registrations should use former.

---

Section 2.3.3 is new information and is potentially important. I think
the reader needs some help to distinguish this section from 2.3.4 (I
do! and my issues/questions here also apply to 2.3.4) and an example
would help (perhaps an example for an IETF review registry).

It may also be helpful to clarify here what type of RFCs we require for
what type of updates. For example, if I create a registry in a Standards
Track RFC that has a Standards Action registration policy, so I need a
Standards Track RFC to change that policy to IETF Review?

---

The last para of 2.3.3 needs to point to 4.4 (as well as 9.5).

---

3.1

  There is no need to mention what the assignment policy is when making
  new assignments in existing registries, as that should be clear from
  the references.

The exception being when there are multiple policies defined for a
registry and a choice is being made.

Equally, when a registry is subdivided into ranges with different
policies, the request must specify the range in order for IANA to
determine which policy applies.

---

3.1

  When drafts need to specify numeric values for
  testing or early implementations, they will either request early
  allocation (see Section 3.4) or use values that have already been set
  aside for testing or experimentation.

This is good, but tends to imply that a draft can state speicific values
from experimental ranges. 3692 makes it clear that this is not the case.

---

3.1

  Note: In cases where authors feel that including the full table is
  too verbose or repetitive, authors should still include the table in
  the draft, but may include a note asking that the table be removed
  prior to publication of the final RFC.

On first and second reading I took this to mean "include the full
existing table from the registry and show your additions." On third
reading (perhaps after adequate port?) I see that you may mean a full
table of the new entries. Maybe this could be wordsmithed?

---

The example at the end of 3.1 includes text that often trips up authors
who detest the future historic tense.

      IANA has assigned an option code value of TBD1 to the DNS
      Recursive Name Server option and an option code value of TBD2 to
      the Domain Search List option from the DHCP option code space
      defined in Section 24.3 of RFC 3315.

It is true that the final RFC text will contain these words ("IANA has
assigned") and at the time of RFC editing this will be inserted. But
authors prefer to write...

      IANA is requested to assign an option code value of TBD1 ...

You use this form in other examples, so I think this is just a
cut'n'paste from an RFC.

---

You might add in 3.4 (since it may be valuable to highlight what was,
but is no longer the case"...

It is not necessary to explicitly mark a registry as allowing early
allocation. [RFC7120] explains all of the considitions under which early
allocation is allowed.

---

Section 4

  The following are some defined policies, most of which are in use
  today.

Of course, that set me to trying to work out which ones are not in use
today. After a while I determined that it's a trick: "all" is a sub-case
of "most".

Maybe this sentence can read...

  The following policies are defined for common usage.

---

Section 4

"strongly RECOMMENDED"

Does that go along with "you know you really, really SHOULD" and
"absolutely MUST"?

---

Section 4

The example...

  Pseudowire Edge to Edge Emulation (PWE3) [RFC4446]

is vague and fails the test of this document. That is, there is no
registry with that name. You could have...

  MPLS Pseudowire Types Registry [RFC4446] 

---

Section 4.1

  There is
  no need for IANA to review such assignments (since IANA does not
  record them)

Perfectly correct, but I would prefer the statement to be reversed as

  IANA does not record assignments from registries or ranges with this
  policy (and therefore there is no need for IANA to review them)

---

4.2

  Experimental Use is similar to Private Use only

d/only/

---

4.2

I would like this section to state:

- IANA does not record assignments from registries or ranges with this
  policy
- It is inappropriate for documents to state explicit values from
  registries or ranges with this policy

---

Section 4.3

  Examples:

      DNS names
      Object Identifiers
      IP addresses

Is it possible to give references for these? Maybe URLs or RFCs?

---

Section 4.4

  It is also important to understand that First Come First Served
  really has no filtering.  Essentially, any request is accepted.  A
  working group or any other entity that is developing protocol based
  on a First Come First Served code point has to be extremely careful
  that the protocol retains wire compatibility with current use of the
  code point.  Once that is no longer true, the new work needs to
  change to a different code point (and register that use at the
  appropriate time).

I'd suggest a paragraph break after "accepted." There is no
consequential flow into the next sentence.

---

Section 4.5

  (Also called "Designated Expert" in earlier editions of this
  document.) For the Expert Review policy, review and approval by a
  designated expert (see Section 5) is required.  The required
  documentation and review criteria for use by the designated expert
  should be provided when defining the registry.  For example, see
  Sections 6 and 7.2 in [RFC3748].

  It is particularly important, when using a designated expert, to give
  clear guidance to the expert, laying out criteria for performing an
  evaluation and reasons for rejecting a request.  When specifying a
  policy that involves a designated expert, the IANA Considerations
  SHOULD contain such guidance.

There is a bit of duplication in this text. I suggest folding the last
two sentences of the first paragraph into the second paragraph.

---

4.10

  IESG Approval is not intended to be used often or as a "common case";
  indeed, it has seldom been used in practice during the period RFC
  2434 was in effect.

s/has/was/

---

Section 5 presents a lot of new material about DEs. Two questions arise:

1. How does a member of the community discover the names and email
  addresses of the DEs?

2. How does the "chair" of a "pool" of DEs get appointed?

---

Section 5.2.1 should prpbably also talk about removing DEs at the whim
of the IESG (and resignations).

---

Section 5.4 doesn't address a question that comes up a lot. Precisely
when should the DE review be done?

We often see it raised as a question at IETF last call, IESG evaluation,
IESG approval, and RFC editor processing. I think this document could
give better guidance, specifically to IANA who are invoked to make
provisional assignments during IETF last call often before a DE has made
a pronouncement.

---

It would be nice if this document also clarified the role of a DE in
assessing an IETF consensus document. Can a DE block an assignment made
by IETF consensus?

---

Section 7

  o  If a document registers an item that is defined and explained
      elsewhere, the registered reference should be to that document,
      and not to the document that is merely performing the
      registration.

I know what you mean, but "reference should be to that document" is
confusing. Maybe...

  o  If a document registers an item but the definition and explanation
      of the item is provided in a second document, the reference in the
      registry should be to the document that provides the definition
      and not to the document that is merely performing the
      registration.

(Although, I would find it helpful to include both references.)

---

Section 8 runs the risk of confusing obsoletion with updating. I think
you are trying to describe both what to do when a new RFC obsoletes an
old RFC that defined and described the registered codepoint, and what
to do when the change is just an update.

The first paragraph and a half are, I think, intended to describe the
replacement. The later text then introduces the case of an update.

However...

  On occasion, an RFC is issued that obsoletes a previous edition of
  the same document.  We sometimes call these "bis" documents, such as
  when RFC 9876 is updated by draft-ietf-foo-rfc9876bis.

Maybe s/updated/obsoleted/

---

Should section 12 discuss the signing and verification of IANA registry
web pages?

It appears that there are several issues to be addressed based on the IETF Last Call.  The biggest of which (to me) revolves around any implications this draft has on the IANA transition plan.  We should discuss this in Honolulu.

IESG/Authors/WG Chairs:

IANA has reviewed draft-leiba-cotton-iana-5226bis-08, which is currently in Last Call, and has the following comments:

This document has been co-authored by IANA Department staff and represents
current best practice for writing an IANA Considerations section in
Internet-Drafts.

There are no IANA actions to be completed upon approval of this document.

The following Last Call announcement was sent out:

From: The IESG
To: IETF-Announce
Reply-To: ietf@ietf.org
Sender:
Subject: Last Call:  (Guidelines for Writing an IANA Considerations Section in RFCs) to Best Current Practice


The IESG has received a request from an individual submitter to consider
the following document:
- 'Guidelines for Writing an IANA Considerations Section in RFCs'
  as Best Current Practice

The IESG plans to make a decision in the next few weeks, and solicits
final comments on this action. Please send substantive comments to the
ietf@ietf.org mailing lists by 2014-10-30. Exceptionally, comments may be
sent to iesg@ietf.org instead. In either case, please retain the
beginning of the Subject line to allow automated sorting.

Abstract


  Many protocols make use of points of extensibility that use constants
  to identify various protocol parameters.  To ensure that the values
  used in these fields do not have conflicting uses, and to promote
  interoperability, their allocation is often coordinated by a central
  authority.  For IETF protocols, that role is filled by the Internet
  Assigned Numbers Authority (IANA).

  To make assignments in a given namespace prudently, IANA needs
  guidance describing the conditions under which new values should be
  assigned, as well as when and how modifications to existing values
  can be made.  This document defines a framework for the documentation
  of these guidelines by specification authors, in order to assure that
  the guidance given to IANA is clear and addresses the various issues
  that are likely in the operation of a registry.

  This is the third edition, and obsoletes RFC 5226.




The file can be obtained via
http://datatracker.ietf.org/doc/draft-leiba-cotton-iana-5226bis/

IESG discussion can be tracked via
http://datatracker.ietf.org/doc/draft-leiba-cotton-iana-5226bis/ballot/


No IPR declarations have been submitted directly on this I-D.

All,
    I have completed my AD evaluation of
draft-leiba-cotton-iana-5226bis and only have a few items that need
addressing prior to IETF Last Call.  Please let me know if you have any
questions on these points...

1. ID-nits complains about several things that should be fixed.

http://tools.ietf.org/idnits?url=http://tools.ietf.org/id/draft-leiba-cotton-iana-5226bis-07.txt

2. I added an IESG Note to the datatracker indicating that the document
shouldn't be approved before the URL in section 1.2 is created.  Should
the document be held until the permalink support noted in section 2.2 is
in place?

3. I am wondering if it would be beneficial to document a few example
questions that requesters should consider in section 2.1.

4. In section 2.2:

* The paragraph on sub-registry creation has a "must be" that I think
should be "MUST be".

* The text on initial assignments and reservations refers to terms with
special meaning.  Should those have a forward reference to section 6
where they are defined?

Regards,
Brian