I want to acknowledge that keeping a "living" document up-to-date is hard, and this document is no exception. Kudos goes out to the authors for trying to dry the ink on the document before the next suggestion comes in.
I also wanted to acknowledge the careful review that Qiufang Ma did as a shepherd for the document. The dilemma for me was to review just the changes or to review the whole document. Since the idea of the -bis is to improve the document, I decided to go with the latter. Section 1, paragraph 1 > This document defines a set of usage guidelines for documents > containing YANG 1.1 [RFC7950] and YANG 1.0 [RFC6020] data models, > including IANA-maintained modules. YANG is used to define the data > structures, protocol operations, and notification content used within > a NETCONF and/or RESTCONF server. YANG is also used to define > abstract data structures [RFC8791]. A NETCONF or RESTCONF server > that supports a particular YANG module will support client NETCONF > and/or RESTCONF operation requests, as indicated by the specific > content defined in the YANG module. Are we defining just usage guidelines, or are we defining other guidelines too? Guidelines such as coding guidelines, guidelines around how IANA Considerations should be written, or guidelines around how IANA handles revisions for YANG modules? So maybe "This document defines guidelines around how YANG modules should be written or maintained", or some such language?? Section 1, paragraph 1 > Many YANG constructs are defined as optional to use, such as the > "description" statement. However, in order to make YANG modules more > useful, it is desirable to define a set of usage guidelines that > entails a higher level of compliance than the minimum level defined > in the YANG specification [RFC7950]. The idea is for a YANG module to be both readable and interoperable, as mentioned below. The description statement helps to satisfy both requirements. How about saying: "However, in order to make YANG modules more readable and interoperable, it is desirable to define a set of descriptive usage guidelines that entails..."? Section 2, paragraph 3 > IANA-maintained module: A YANG module that is maintained by IANA > (e.g., "iana-tunnel-type" [RFC8675] or "iana-pseudowire-types" > [RFC9291]). > > IETF module: A YANG module that is published by the IETF and which > is not maintained by IANA. What does it mean for a YANG module to be "maintained" by IANA? Currently, IETF YANG modules are extracted and hosted in the IANA rsync site. However, as you say, they are not "maintained" by them. I think what is meant here is IANA YANG modules that are updated or administered by IANA based on updates done to the corresponding IANA registry. Section 3.2.1, paragraph 0 > Example modules are not code components. The <CODE BEGINS> > convention MUST NOT be used for example modules. If we want to validate examples included within the document, something that is mentioned later in the document, they will need to be extracted from the document. That happens today when it is identified as code with a <CODE BEGINS> <CODE ENDS> tag. However, it is clear that not all examples are complete examples. Sometimes, they are just snippets of code. Under these conditions, this guidance needs to be nuanced to identify examples that can and should be validated. One way to do that would be to use <CODE BEGINS> and <CODE ENDS> tags for examples that should be extracted and validated. Section 3.7.1, paragraph 2 > The "<module-name>" YANG module defines a data model that is > designed to be accessed via YANG-based management protocols, such as > NETCONF [RFC6241] and RESTCONF [RFC8040]. These protocols have to > use a secure transport layer (e.g., SSH [RFC4252], TLS [RFC8446], and > QUIC [RFC9000]) and have to use mutual authentication. I am not sure what to make of the sentence, "These protocols have to use a secure transport layer ... and have to use mutual authentication." It is not like the protocols have a choice. Moreover, "have to" is not a 2119 keyword, if there was an intention to specify that a secure transport MUST be used. How about saying, "These protocols use a secure transport layer ... and MUST use mutual authentication."? Section 3.7.1, paragraph 18 > By default, [RFC4252], [RFC6241], [RFC8040], [RFC8446], [RFC9000], > and RFC AAAA (or future RFCs that replace any of them) are listed > as informative references unless normatively cited in other > sections of the document that specifies the YANG module. It should be made clear to the RFC Editor that AAAA refers to the number that will be assigned to this document when it becomes an RFC. A similar comment is made later in the document. Section 3.10, paragraph 6 > The "yanglint" program is also freely available from GitHub. Should a minimum version of yanglint be specified here, e.g., 2.1.30, the version used by datatracker? Section 4.1, paragraph 5 > It is suggested that a stable prefix be selected that represents the > entire organization. All normative YANG modules published by the > IETF MUST begin with the prefix "ietf-". Another standards > organization, such as the IEEE, might use the prefix "ieee-" for all > YANG modules. How about IANA? Should this paragraph say something about how IANA modules should be named? Section 4.2, paragraph 0 The first paragraph talks about identifier names in a section titled "Prefixes". Can this be moved to 4.3.1, where we talk about the Identifier Naming Convention? Section 4.2, paragraph 9 > * The proper module prefix MUST be used for all identifiers imported > from other modules. What is a "proper module prefix"? Also, should there be guidance that the importing module should use the prefix defined by the imported module? Section 4.2, paragraph 9 > * The proper module prefix MUST be used for all identifiers included > from a submodule. Same comment here. Section 4.4, paragraph 0 > In general, it is suggested that substatements containing very common > default values SHOULD NOT be present. The substatements listed in > Table 1 are commonly used with the default value, which would make > the module difficult to read if used everywhere they are allowed. This is excellent advice. Similarly, should there be guidance for statements that ideally should have default values, e.g., boolean? It is useful for a user/operator to know and not have to type the default for a boolean if the default behavior is intended. Section 4.6.2, paragraph 12 > The "derived-from-or-self" function SHOULD be used instead of an > equality expression for identityref values. This allows the > identities to be conceptually augmented. > > Example: > > // assume "ex" is the prefix of the module where the identity > // name-format-null is defined > > // do not use > when "md-name-format = 'name-format-null'"; > > // this is preferred > when "derived-from-or-self(md-name-format, 'ex:name-format-null')"; I always felt this instruction was out of place. The section is under XPath Usage and is talking about functions in XPath, while this example is talking about functions for YANG types. Maybe break it out into its own section and call it "Functions for YANG types." Section 4.8, paragraph 5 > The "description" statement MUST be present. For modules published > within IETF documents, the appropriate IETF Trust Copyright text MUST > be present, as described in Section 3.1 and contain the following > statement: > > All revisions of IETF and IANA published modules can be found at > the YANG Parameters registry: https://www.iana.org/assignments/ > yang-parameters. It is not clear from this whether the indented statement is a MUST or a SHOULD as far as including it in the Copyright text. It is a useful statement to have, but I do not know if it is a MUST. Maybe RECOMMENDED? Section 4.8, paragraph 6 > A "revision" statement MUST be present for each published version of > the module. The "revision" statement MUST have a "reference" > substatement. It MUST identify the published document that contains > the module. Modules are often extracted from their original > documents, and it is useful for developers and operators to know how > to find the original source document in a consistent manner. The > "revision" statement MAY have a "description" substatement. For > convenience, the description text of a new published revision may > summarize any changes made to a module compared to the previous > published revision. Typically, that list is a YANG-specific subset > of the summary of changes listing any changes made from the RFC being > updated or obsoleted as per [ID-Guidelines]. Is the "revision" or the "description" statement that identifies the original document which the module was extracted from? Currently, we include the following text as part of the "description" statement. This version of this YANG module is part of RFC XXXX (https://www.rfc-editor.org/info/rfcXXXX); see the RFC itself for full legal notices. Section 4.19.2, paragraph 14 > This practice is not safe for identities defined in a common module > such as "iana-if-type" because the client is not required to know > about "my-module" just because it knows about the "iana-if-type" > module. It is not clear to me what is "my-module" is referring to. I think it means "example-module" which has a prefix of "mymod". We should change it to say "example-module." Section 4.30.1, paragraph 3 > For the sake of consistency, better flexibility to support new > values, and maintaining IANA registries as the unique authoritative > source of information, when such an information is maintained in a > registry, this document encourages the use of IANA-maintained > modules. Could this paragraph be reworded as follows: "For the sake of consistency and ability to support new values while maintaining IANA registries as the unique authoritative source of information, this document encourages the use of IANA-maintained modules as the single source of information."? Section 4.30.2, paragraph 5 > Designers of IANA-maintained modules MAY supply the full initial > version of the module in a specification document that registers the > module or only a script to be used (including by IANA) for generating > the module (e.g., an XSLT stylesheet as in Appendix A of [RFC9108]). > For both cases, the document that defines an IANA-maintained module > MUST include a note indicating that the document is only documenting > the initial version of the module and that the authoritative version > is to be retrieved from the IANA registry. Also, the IANA-maintained > module MUST include the following note indicating the RFC that > registered the initial version of the IANA-maintained module: In light of what happened with the ACL extension module, maybe we might want to update this guidance to just provide the full initial module. Section 4.30.3, paragraph 2 > * An IANA request to add a note to the authoritative IANA registry > to indicate that any change to the registry must be reflected into > the corresponding IANA-maintained module. Perhaps - "A request to IANA to add a note in the authoritative IANA registry to indicate that any changes to the registry must be accompanied by an update to the corresponding IANA-maintained module."? Section 5.2, paragraph 0 > Also, this document requests IANA to update the reference for the > "YANG Module Names" registry under the "YANG Parameters" registry > group to point to the RFC number that will be assigned to this > document as it contains the template necessary for registration in > Appendix B. I am not sure that the reference to the "YANG Modules Names" registry should be moved from RFC6020 to this document, even if it contains a template for registration. That template is much like any other YANG module, and even RFC7950 decided to leave the registry in RFC6020. Section 5.3, paragraph 7 > OLD: > > All module and submodule names in the registry MUST be unique. > > All XML namespaces in the registry MUST be unique. > > NEW: > Modules and their revisions are maintained in the registry. > > A module and all its revisions MUST have the same name and > namespace. > > All initial version module and submodule names in the registry > MUST be unique. > > All XML namespaces of initial version modules in the registry MUST > be unique. I believe this update in guidance is unncessary and confusing. RFC 7950 says: The name of the file SHOULD be of the form: module-or-submodule-name ['@' revision-date] ( '.yang' / '.yin' ) "module-or-submodule-name" is the name of the module or submodule, and the optional "revision-date" is the latest revision of the module or submodule, as defined by the "revision" statement (Section 7.1.9). A module or a submodule has a name and it has a revision. Clearly, a module when combined with its revisions cannot have the same name. If revisions are not part of the name, the original guidance stands. Plus what happened to submodules? If the second sentence in the guidance is not true, the third sentence is redundant. Finally, the last statement in the NEW section does not make sense as the XML namespace does not change with every revision of the module. All in all, this section should be dropped, and if this is the only thing that was updating RFC6020, it should drop the sentence that it is updating RFC6020. Section 5.4, paragraph 7 > When this registry is modified, the YANG module "iana-foo" > [IANA_FOO_URL] must be updated as defined in RFC IIII. The guideline adds a note to RFC Editor as part of the description statement in the YANG module. Instead, it would be better for this document to suggest that authors should have a separate section up front in their document called "Note to the RFC Editor" outlining all the steps the editors needs to take for references such as IIII, AAAA, XXXX or dates inserted in the document. For example, in this document, the reference of what to do with IIII or the date 2023-07-23 in this document comes much later in the appendix of this document, which is much too late. Section 6, paragraph 1 > This document defines documentation guidelines for NETCONF or > RESTCONF content defined with the YANG data modeling language; > therefore, it does not introduce any new or increased security risks > into the management system. I think the document is defining more than just documentation guidelines and would therefore drop the word "documentation". Would it better to say: "This document defines guidelines for NETCONF or RESTCONF use of content defined by the YANG data modeling language. It does not introduce any new or increased security considerations that need to be discussed here.". Check whether Expert Review is an appropriate registration policy here. Possible DOWNREF from this Best Current Practice doc to [W3C.REC-xpath]. If so, the IESG needs to approve it. Possible DOWNREF from this Best Current Practice doc to [ID-Guidelines]. If so, the IESG needs to approve it. Found terminology that should be reviewed for inclusivity; see https://www.rfc-editor.org/part2/#inclusive_language for background and more guidance: * Term "dummy"; alternatives might be "placeholder", "sample", "stand-in", "substitute" * Term "native"; alternatives might be "built-in", "fundamental", "ingrained", "intrinsic", "original" ------------------------------------------------------------------------------- NIT ------------------------------------------------------------------------------- All comments below are about very minor potential issues that you may choose to address in some way - or ignore - as you see fit. Some were flagged by automated tools (via https://github.com/larseggert/ietf-reviewtool), so there will likely be some false positives. There is no need to let me know what you did with these suggestions. "Abstract", paragraph 0 > This memo provides guidelines for authors and reviewers of > specifications containing YANG modules, including IANA-maintained > modules. Recommendations and procedures are defined, which are > intended to increase interoperability and usability of Network > Configuration Protocol (NETCONF) and RESTCONF protocol > implementations that utilize YANG modules. This document obsoletes > RFC 8407. s/RESTCONF protocol/RESTCONF Protocol/ Section 1, paragraph 1 > The standardization of network configuration interfaces for use with > network configuration management protocols, such as the Network > Configuration Protocol (NETCONF) [RFC6241] and the RESTCONF protocol > [RFC8040], requires a modular set of data models that can be reused > and extended over time. s/RESTCONF protocol/RESTCONF Protocol/ Section 3.8.3.2, paragraph 4 > IANA is requested to register the following YANG module in the "YANG > Module Names" subregistry [RFC6020] within the "YANG Parameters" > registry. s/requested to register/requested to update/ Section 4.2, paragraph 1 > All YANG definitions are scoped by the module containing the > definition being referenced. This allows definitions from multiple > modules to be used, even if the names are not unique. In the example > below, the identifier "foo" is used in all three modules: s/This allows definitions from multiple modules to be used, even if the names are not unique/This allows the same name to be used in multiple moodules, even if they are not unique/ Section 4.29, paragraph 1 > For contexts where YANG is used to model abstract data structures > (e.g., protocol messages), the use of [RFC8791] is RECOMMENDED > compared to the "yang-data" extension statement [RFC8040]. s/the use of [RFC8791]/the use of "structure" extension statement [RFC8791/ Section 4.29, paragraph 1 > Examples of modules that rely upon [RFC8791] are [RFC9132] or > [RFC9195]. s/rely upon [RFC8791]/rely upon the "structure" extension statement [RFC8791]/ Section 4.30.3, paragraph 2 > * An IANA request to add a note to the page displaying the > information about the IANA-maintained module that new values must > not be directly added to the module, but to an authoritative IANA > registry. s/An IANA request/A request to IANA/ s/the module, but to an/the module. They should be added to an/ Section 4.30.3, paragraph 7 > - If a new registration uses an identifier that does not comply > with the naming conventions listed in Section 4.3.1, IANA > should check if a guidance to generate legal identifiers was > supplied in the RFC that specified the initial version of the > module. If no such guidance is available, IANA should check > the latest revision of the IANA-maintained module for similar > patterns. If failed, IANA should seek advice from relevant > registry experts (e.g., designated experts for a registry with > Expert Review policy (Section 4.5 of [RFC8126]) or responsible > Area Director). s/If failed/If all else fails/ Section 4.30.3, paragraph 8 > * An indication whether experimental values are included in the > IANA-maintained module. Absent such an indication, experimental > values MUST NOT be listed in the IANA-maintained module. s/An indication whether experimental values are included/A direction whether experimental values should be include/ s/Absent such an indication/If no direction is provided/ Section 5.3, paragraph 1 > IANA considerations to register YANG module and submodule names are > specified in Section 14 of [RFC6020]. This document amends the > guidance on names unicity as follows: s/names unicity/the uniqueness of names/ Reference [RFC7223] to RFC7223, which was obsoleted by RFC8343 (this may be on purpose). These URLs in the document can probably be converted to HTTPS: * http://www.w3.org/TR/1999/REC-xpath-19991116 * http://www.rfc-editor.org/styleguide/ Section 3.5, paragraph 2 > tive section SHOULD include a mention about the classification of a given mo > ^^^^^^^^^^^^^^^^^ Did you mean simply "mention the"? You do not need the word "about" here. "I", paragraph 9 > igned to this document when it becomes a RFC. 3.8. IANA Considerations Sectio > ^ Use "an" instead of "a" if the following word starts with a vowel sound, e.g. "an article", "an hour". Section 4.3.1, paragraph 7 > under some circumstances to help detecting anomalies. Relaxing validation c > ^^^^^^^^^ The verb "help" is used with an infinitive. Section 4.6.5, paragraph 1 > he original source document in a consistent manner. The "revision" statement > ^^^^^^^^^^^^^^^^^^^^^^ Consider replacing this phrase with the adverb "consistently" to avoid wordiness. Section 4.9, paragraph 3 > be ordered from most restrictive to least restrictive types. In the followin > ^^^^^ A determiner may be missing. Section 4.11.2, paragraph 4 > nfiguration anyxml nodes will not supported. If there are referential integr > ^^^^^^^^^ The modal verb "will" requires the verb's base form. Section 7.2, paragraph 21 > or the comments. Lou Berger suggested to include more details about IANA con > ^^^^^^^^^^^^^^^^^^^^ The verb "suggested" is used with the gerund form. Mahesh Jethanandani [email protected]
_______________________________________________ netmod mailing list -- [email protected] To unsubscribe send an email to [email protected]
