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

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?

Thank you for addressing my comments.

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?