Mike Bishop has entered the following ballot position for draft-ietf-netmod-yang-semver-26: 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-semver/ ---------------------------------------------------------------------- DISCUSS: ---------------------------------------------------------------------- # IESG review of draft-ietf-netmod-yang-semver-26 CC @MikeBishop ## Discuss ### Section 4.5, paragraph 9 ``` ii "X.Y.Z_compatible" - the artifact version SHOULD be updated to "X.Y.Z+1_compatible". ``` If I'm reading this correctly, this suggests that, from a base of 3.2.0, versions 3.2.1 (on the main branch) and 3.2.1_compatible (child of 3.2.0_compatible) might contain different changes relative to their parent versions? This seems guaranteed to confuse users. The natural assumption is that anything labeled 3.2.1 contains the main branch's 3.2.1 _plus_ whatever changes are indicated by the suffix. This seems particularly problematic given the matching rules in 5.2. ---------------------------------------------------------------------- COMMENT: ---------------------------------------------------------------------- ## Comments ### Section 4.3, paragraph 4 "MUST only" is potentially ambiguous. Does it mean "MUST be present if COMPAT is present and MUST NOT be present otherwise? If so, consider a single optional element that MUST begin with the character '_' as a cleaner way to express this. ### Section 4.4, paragraph 12 What does one do with "can indicate" here? Either it indicates this, or it indicates many things including this. If many things, what is the scope of things it indicates? ### Section 4.4.3, paragraph 4 ``` software development. It is recommended to avoid only incrementing the PATCH digit on the main branch of YANG modules. See Appendix B Scenario 2 for an illustration and explanation. ``` This says that changes on the main branch should alter more than the PATCH number, but your example seems to argue for the exact opposite. Should this instead say "It is recommended that only the main branch of YANG modules increment the PATCH number"? Or am I misunderstanding? ### Section 5.2, paragraph 15 For the reasons stated here, I'm slightly surprised there's not a corresponding max-version, in case there's a breaking change which the current module doesn't yet support. ### Section 6.1.2.1, paragraph 1 ``` For example, if a module or submodule started out in the pre-NMDA ([RFC8342] ) world, and then had NMDA support added without removing any legacy "state" branches -- and you are looking to add additional new features -- a sensible choice for the target YANG Semver would be 1.2.0 (since 1.0.0 would have been the initial, pre-NMDA release, and 1.1.0 would have been the NMDA revision). ``` This can probably be reworded to remove the "world" terminology and the use of the second-person. ### Too many authors The document has six authors, which exceeds the recommended author limit. Has the sponsoring AD agreed that this is appropriate? ## Nits 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. ### Typos #### Section 1, paragraph 1 ``` - [I-D.ietf-netmod-yang-module-versioning] puts forth new concepts - ------------- - relating to modified rules for updating YANG modules and submodules, - ------------ ``` #### Section 1, paragraph 2 ``` - The goal being to add a human readable version identifier that - --------- ^^^^^ ^ + This adds a human-readable version identifier that + ^ + ^ ``` ### Outdated references Document references `draft-clacla-netmod-yang-model-update-06`, but `-26` is the latest available revision. ### Grammar/style #### Section 4.4.1, paragraph 1 ``` the versions could look like, from oldest version to newest: 0.1.0 - first p ^^^^^^ ``` A determiner may be missing. #### Section 4.6.2, paragraph 2 ``` s section and the IETF-specific sub-section below provide YANG Semver-specif ^^^^^^^^^^^ ``` This word is normally spelled as one. _______________________________________________ netmod mailing list -- [email protected] To unsubscribe send an email to [email protected]
