Hi Mahesh, Thank you for the review.
A diff to track the changes can be seen here: https://author-tools.ietf.org/api/iddiff?url_1=https://netmod-wg.github.io/rfc8407bis/draft-ietf-netmod-rfc8407bis.txt&url_2=https://netmod-wg.github.io/rfc8407bis/ad-review/draft-ietf-netmod-rfc8407bis.txt. Please see inline for more context. Cheers, Med De : Mahesh Jethanandani <[email protected]> Envoyé : dimanche 13 avril 2025 23:13 À : [email protected] Cc : NETMOD Group <[email protected]> Objet : AD review of draft-ietf-netmod-rfc8407bis-22 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. [Med] I'm OK with both as the intent is to enhance our guidance. As you can see below, I accepted changes for text inherited from 8407 because I think we need to have clear guidance and revisit text when needed. Nothing is frozen ;-) 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?? [Med] This is inherited from 8407. Dropped "usage". 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..."? [Med] This is inherited from 8407. Your edits work for me, though. Updated. 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. [Med] It is maintained by IANA in the same that it maintains a 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. [Med] Good point, but I guess your comment should be for Section 3.12, not 3.2.1. Section 3.12 has the following: "Examples MUST be validated". Added this NEW: "In order to ease extraction and validation of examples, it is RECOMMENDED to use code markers." 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."? [Med] As you know "Specifically, normative text does not require the use of these key words." (RFC8174). I prefer the current wording for consistency of the full paragraph. 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. [Med] We do have a note for this: * Note to the RFC Editor: Please replace "AAAA" through the document with the RFC number assigned to this document.¶<https://datatracker.ietf.org/doc/html/draft-ietf-netmod-rfc8407bis-22#section-1-9.1.1> 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? [Med] That would be quickly stale. I suggest to not mention that. 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? [Med] Good point. I thought we have one. Added. 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? [Med] This is about the prefix of the module name. Updated to avoid confusion. 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"? [Med] This is inherited from 8407. This means the prefix declared for the imported module. Not sure a change is needed. Also, should there be guidance that the importing module should use the prefix defined by the imported module? [Med] We do already have that in RFC7950: "To improve readability of YANG modules, the prefix defined by a module SHOULD be used when the module is imported, unless there is a conflict. " Added this NEW: Consistent with {{Section 7.1.4 of !RFC7950}}, the prefix defined by a module SHOULD be used when the module is imported, unless there is a conflict. Section 4.2, paragraph 9 > * The proper module prefix MUST be used for all identifiers included > from a submodule. Same comment here. [Med] Same response 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. [Med] I have considered this one but give it up as there are implications on uses in already published module which may have distinct defaults. The example right after this text is a hint ;-) 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." [Med] I hear you but I followed a rule preserve the section numbering as much vs 8407 (ease upgrading already used links out there). Will leave this one as it is. 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? [Med] I think MUST is justified as we want to ensure consistency among all IETF published RFCs. 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. [Med] We have this in both. See the example right after. Updated the IETF template to make this clearer. 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." [Med] This was inherited from 8407. I always interpret this as a generalization rather than the specific "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."? [Med] This is better. Fixed. Thanks. 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. [Med] I think this text sketch the direction we need to follow assuming we have the appropriate tooling. In both cases the text allows to supply the full initial version in draft versions. Let's work to have the tooling set. I will keep the current text as it is. 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."? [Med] I added "That is, any changes to the registry must be accompanied by an update to the corresponding IANA-maintained module.". Right after the current text. 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. [Med] The request is not to change 6020 but 8407 mention: CURRENT: YANG Module Names Registration Procedure(s) RFC Required Reference [RFC6020<https://www.iana.org/go/rfc6020>][RFC8407<https://www.iana.org/go/rfc8407>] Updated the text accordingly. 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. [Med] The practice followed by IANA so far is not aligned with 6020 (agreement with previous ADs as I was told). For example "All XML namespaces in the registry MUST be unique" is not true. This section adjusts our reference text with the practice. 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. [Med] It doesn't. This note is added to a registry and not part of a 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. [Med] IANA section was reviewed extensively with IANA team. We have added some part/section per their request. Will leave this as. 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.". [Med] OK but without « here". Check whether Expert Review is an appropriate registration policy here. [Med] Not sure to get the comment. This was cited as an example. Possible DOWNREF from this Best Current Practice doc to [W3C.REC-xpath]. If so, the IESG needs to approve it. [Med] This one is OK. This is not an RFC + already cited as such in 8407. Possible DOWNREF from this Best Current Practice doc to [ID-Guidelines]. If so, the IESG needs to approve it. [Med] This one is OK. This is not an RFC + already cited as such in 8407. 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" [Med] ACK ------------------------------------------------------------------------------- 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/ [Med] OK 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/ [Med] OK 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/ [Med] Good catch. 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/ [Med] OK but with s/they/names 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/ [Med] ACK 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]/ [Med] OK 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/ [Med] OK but with s/They/ These values 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/ [Med] Like this one :-) 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/ [Med] OK but with s/direction/instruction 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/ [Med] OK Reference [RFC7223] to RFC7223, which was obsoleted by RFC8343 (this may be on purpose). [Med] This is 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/ [Med] ACK. 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. [Med] Left the current. "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". [Med] Failed to find this one Section 4.3.1, paragraph 7 > under some circumstances to help detecting anomalies. Relaxing validation c > ^^^^^^^^^ The verb "help" is used with an infinitive. [Med] Updated. 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. [Med] Kept the current Section 4.9, paragraph 3 > be ordered from most restrictive to least restrictive types. In the followin > ^^^^^ A determiner may be missing. [Med] Left as it is. 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. [Med] Fixed 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. [Med] Left this one as it is. ____________________________________________________________________________________________________________ Ce message et ses pieces jointes peuvent contenir des informations confidentielles ou privilegiees et ne doivent donc pas etre diffuses, exploites ou copies sans autorisation. Si vous avez recu ce message par erreur, veuillez le signaler a l'expediteur et le detruire ainsi que les pieces jointes. Les messages electroniques etant susceptibles d'alteration, Orange decline toute responsabilite si ce message a ete altere, deforme ou falsifie. Merci. This message and its attachments may contain confidential or privileged information that may be protected by law; they should not be distributed, used or copied without authorisation. If you have received this email in error, please notify the sender and delete this message and its attachments. As emails may be altered, Orange is not liable for messages that have been modified, changed or falsified. Thank you.
_______________________________________________ netmod mailing list -- [email protected] To unsubscribe send an email to [email protected]
