Ballot for draft-leiba-cotton-iana-5226bis
Discuss
Yes
No Objection
Recuse
Note: This ballot was opened for revision 09 and is now closed.
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.
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?
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"
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.
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.
thanks for addressing my DISCUSS point.
Thank you for doing this work!
WFM genart review discussion looks closed off to my satisfaction.
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.
In full support of the reviews which are in by now!
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)?
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"
I appreciate the robust reviews and discussion thus far.
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.
I share the concerns regarding the length of this document.