Mohamed Boucadair has entered the following ballot position for draft-ietf-netmod-yang-module-filename-11: Discuss
When responding, please keep the subject line intact and reply to all email addresses included in the To and CC lines. (Feel free to cut this introductory paragraph, however.) Please refer to https://www.ietf.org/about/groups/iesg/statements/handling-ballot-positions/ for more information about how to handle DISCUSS and COMMENT positions. The document, along with other ballot positions, can be found here: https://datatracker.ietf.org/doc/draft-ietf-netmod-yang-module-filename/ ---------------------------------------------------------------------- DISCUSS: ---------------------------------------------------------------------- Hi Per, Thank you for the effort put into this document. Also, thanks to Aihua Guo for the OPSDIR and Per for engaging and addressing that review. Please find below some points for DISCUSSion: # Guidance The name convention defined so far in various RFCs are as follows: RFC 6020 YANG modules and submodules are typically stored in files, one module or submodule per file. The name of the file SHOULD be of the form: module-or-submodule-name ['@' revision-date] ( '.yang' / '.yin' ) RFC 7950 YANG modules and submodules are typically stored in files, one "module" or "submodule" statement per file. The name of the file SHOULD be of the form: module-or-submodule-name ['@' revision-date] ( '.yang' / '.yin' ) RFC 9907: The "<CODE BEGINS>" tag MUST be followed by a string identifying the file name specified in Section 5.2 of [RFC7950]. The name string form that includes the revision date SHOULD be used. The revision date MUST match the date used in the most recent revision of the module. The convention is drawn with a clear guidance on what a name file name layout may look like. This document adopts a formulation that I think is ambiguous. CURRENT: If a revision has an associated YANG semantic version (ysv:version) then a YANG file MUST be created that use the YANG semantic version in the file name. Additionally, a YANG file with the revision-date MAY be created. The name of the files SHOULD be of the form: ## I don’t understand “created” part as that semver is already recorded in an existing file. ## Why isn’t sufficient to follow the same pattern in 6020/7950/9907 and focus mainly on the name pattern? ## Because of tooling and other deployment constraints, do we really need to have that MUST? Shouldn’t that be a SHOULD? # Doesn’t CURRENT 2 cover the behavior in CURRENT 1? CURRENT 1: If a revision has an associated YANG semantic version (ysv:version) then a YANG file MUST be created that use the YANG semantic version in the file name. Additionally, a YANG file with the revision-date MAY be created. The name of the files SHOULD be of the form: CURRENT 2 If the YANG module (or submodule) has an associated YANG semantic version (ysv:version), then a file name that use the YANG semantic version MUST be created. In addition, a file with the revision date in the file name MAY be created as well. # Sanity Check Existing guidance has a MUST to make sure the name mirrors what is in the file. I think that something similar is needed for this convention as well. RFC 9907: The revision date MUST match the date used in the most recent revision of the module. # IANA Actions vs. Authors Actions CURRENT: The registry MUST create a file with a YANG semantic version if the YANG module (or submodule) has an associated YANG semantic version (ysv:version). The registry MUST also create a file with the YANG module using a file name with the revision date. It MUST be ensured that the files' contents are identical. ## The IANA action is to update the registry to support both conventional and new layout. ## Except IANA-maintained modules, IANA does not “create” files. Shouldn’t that part of the guidance be for authors? ## Please avoid normative language in IANA Section per the IESG statement on the matter. ---------------------------------------------------------------------- COMMENT: ---------------------------------------------------------------------- # Authoritative source CURRENT: in the module file name, makes it possible to quickly identify the module revision; As there may be deviation between a filename and its content, inferring the ver from the filename may be misleading. I think that we need a caution that the authoritative source is still what is in the file itself, not the filename. # The promise below is true when a check is in place (see my comment about Sanity Check) CURRENT: Having the YANG semantic version visible in the file name will make it easier to handle large sets of YANG modules. # More Operational Considerations I suggest to cover the following items as well: * A statement that the convention does not impact modules already in use. * A brief text about tooling impact, including migration in deployment # Nits ## OLD: This document presents YANG module file name convention NEW: This document presents a YANG module file name convention ## won't age well OLD: the current YANG module file name using NEW: the YANG module file name using ## OLD: This document defines the YANG module file name convention. NEW: This document defines a YANG module file name convention. ## s/a glance withouth the/ a glance without the Cheers, Med _______________________________________________ netmod mailing list -- [email protected] To unsubscribe send an email to [email protected]
