[netmod] Re: Mike Bishop's Discuss on draft-ietf-netmod-yang-semver-26: (with DISCUSS and COMMENT)

["Joe Clarke (jclarke)" <[e-mail]>]

I echo Rob’s thanks, Mike.  That said, we attempted to address your remaining balloted items, as well as add more clarity to the use of _COMPAT and how to bump versions.  I’ve hosted the side-by-side diff at https://www.marcuscom.com/draft-ietf-netmod-yang-semver.diff.html and attached it here as well.

Joe

From: Rob Wilton (rwilton) <[e-mail]>
Date: Monday, June 8, 2026 at 04:27
To: Mike Bishop <[e-mail]>
Cc: The IESG <[e-mail]>; [e-mail] <[e-mail]>; [e-mail] <[e-mail]>; [e-mail] <[e-mail]>; [e-mail] <[e-mail]>
Subject: Re: Mike Bishop's Discuss on draft-ietf-netmod-yang-semver-26: (with DISCUSS and COMMENT)

Hi Mike,

Thanks for clearing, and your initial review and comments with a fresh perspective.  We will look to see if we can add some additional text to make the expected behaviour and use case a bit clearer.

As for your alternative suggestion, we did spend a lot of time thinking , discussing, and testing out alternatives (including a 4th version number field).  There is, not surprisingly, no perfect solution here.

Kind regards,
Rob


From: Mike Bishop <[e-mail]>
Date: Friday, 5 June 2026 at 20:16
To: Rob Wilton (rwilton) <[e-mail]>
Cc: The IESG <[e-mail]>; [e-mail] <[e-mail]>; [e-mail] <[e-mail]>; [e-mail] <[e-mail]>; [e-mail] <[e-mail]>
Subject: Re: Mike Bishop's Discuss on draft-ietf-netmod-yang-semver-26: (with DISCUSS and COMMENT)

That scenario clarification helps a lot. I still think the choice to increment the patch version for changes on the "twig" is questionable; if I were designing this, I would probably add a fourth number field after the tag to indicate revs on the twig, so that a user can be guaranteed that 3.2.5_compatible_3 was derived from 3.2.5 of the main branch with 3 additional changes that aren't in 3.2.6. However, that feedback is not on the scale of a DISCUSS. I'll adjust my ballot, but I would encourage additional text outlining the scenario and usage.

________________________________
From: Rob Wilton (rwilton) <[e-mail]>
Sent: Thursday, June 4, 2026 7:31 AM
To: Mike Bishop <[e-mail]>
Cc: The IESG <[e-mail]>; [e-mail] <[e-mail]>; [e-mail] <[e-mail]>; [e-mail] <[e-mail]>; [e-mail] <[e-mail]>
Subject: Re: Mike Bishop's Discuss on draft-ietf-netmod-yang-semver-26: (with DISCUSS and COMMENT)

Hi Mike,

I think that the disconnect is probably on this bit "Someone outside the WG introduces a backward-compatible change, so they produce 3.2.1_compatible".  The branching being introduced does not allow a third party to create and publish their own patched version of a YANG module (e.g., similar to the Linux distribution behaviour that you described).  There is only a single owner/publisher or a YANG module and no-one else can change that module definition.  If their implementation doesn't conform then this must use YANG deviations to advertise their non conformance, but that goes into a separate yang module (e.g., perhaps something like vendor-ietf-interface-deviations.yang if they had deviations to ietf-interfaces.yang)

Instead, the limited branching is designed to allow the owner/publisher of a YANG module to patch a fix to an older version of that YANG module after they have already published a new version so that users of that old module version are not forced to update to the latest version.  For IETF YANG modules (and IANA) then we would expect the WGs to always just update the most recent versions of the YANG modules and hence they would entirely follow the regular Semver rules.  E.g., if you were on 3.2.0, then the next version would always be 4.0.0, 3.3.0 or 3.2.1 depending on what type of changes were in the next module release by the WG.

Really, this modified semver is expected to be more helpful for vendor YANG modules:

Say a vendor publishes vendor-interfaces.yang@1.0.0, then a new version 1.1.0 after introducing new backwards compatible functionality.  vendor-interfaces@1.0.0 has been released to the market on various devices.  A customer using one of those devices+releases notices a bug in the pattern statement (e.g., a regex) that they need to be fixed because it allows values that it should not.  They ask the vendor to fix this regex, which by the YANG versioning rules ends up being a non-backwards-compatible change.  The vendor could publish this as 2.0.0, but that would be confusing because it is not built on the 1.1.0 content, so instead, what the vendor does is (i) produce a 2.0.0 version built on 1.1.0 that also contains the non-backwards-compatible fix.  But the vendor also produces a 1.0.1_non_compatible version which is just the 1.0.0 code with the fixed regex.  They can then ship the 1.0.1_non_compatible version of the module to the customer as a patch update to the older shipping release.  All new product releases would just get/use the 2.0.0 version.  I.e., the 1.0.1_non_compatible is really just on a temporary twig branch for a bugfix that would disappear over time.

Does that help clarify?


  *
If I get 3.2.5_compatible, then I cannot reliably conclude anything about what it contains from what branch except that it (SHOULD have) diverged from the mainline no further back than 3.2.0. "Limited complexity" seems like it substantially understates this.

If you get a 3.2.5_compatible release that you know that it is backwards compatible to all the 3.2.0 release and all other prior releases on the 3.2.0 branch, and that it is backwards compatible to the 3.1.0 and 3.0.0 releases as well (as per normal Semver rules).

Kind regards,
Rob


From: Mike Bishop <[e-mail]>
Date: Wednesday, 3 June 2026 at 20:00
To: Rob Wilton (rwilton) <[e-mail]>
Cc: The IESG <[e-mail]>; [e-mail] <[e-mail]>; [e-mail] <[e-mail]>; [e-mail] <[e-mail]>; [e-mail] <[e-mail]>
Subject: Re: Mike Bishop's Discuss on draft-ietf-netmod-yang-semver-26: (with DISCUSS and COMMENT)

Okay, let's trace through. Perhaps I'm still misunderstanding.

Suppose we start with a version 3.2.0 as the base. Someone outside the WG introduces a backward-compatible change, so they produce 3.2.1_compatible, both incrementing the number and adding the tag. Meanwhile, the working group makes an editorial change which they publish as 3.2.1. So 3.2.1_compatible contains some non-editorial non-breaking change which is not in the mainline 3.2.1; 3.2.1 contains some editorial change which is not in 3.2.1_compatible. 3.2.2_compatible might contain 3.2.1's editorial change plus some new non-breaking change, or it might contain 3.2.1_compatible's NBC plus some additional editorial or non-breaking change. I can't tell from the version number; the one thing I'm pretty sure it doesn't contain is the change which will eventually be in the mainline's 3.2.2, which is what a naive user would assume it does containe.

If I get 3.2.5_compatible, then I cannot reliably conclude anything about what it contains from what branch except that it (SHOULD have) diverged from the mainline no further back than 3.2.0. "Limited complexity" seems like it substantially understates this.

(Oh, and I just noticed two instances of "comptible" rather than "compatible", in case I didn't catch those earlier.)
________________________________
From: Rob Wilton (rwilton) <[e-mail]>
Sent: Wednesday, June 3, 2026 5:31 AM
To: Mike Bishop <[e-mail]>
Cc: The IESG <[e-mail]>; [e-mail] <[e-mail]>; [e-mail] <[e-mail]>; [e-mail] <[e-mail]>; [e-mail] <[e-mail]>
Subject: Re: Mike Bishop's Discuss on draft-ietf-netmod-yang-semver-26: (with DISCUSS and COMMENT)

Hi Mike,

No, 3.2.2_compatible must still be built on 3.2.1 and hence include all the diffs from 3.2.0 to 3.2.1.

If you just start with an example history of editorial changes then you would just increment the patch number.  E.g., 3.2.0 => 3.2.1 => 3.2.2 => 3.2.3, ...  Someone reading those version numbers knows that the diff from 3.2.0 to 3.2.3 is only editorial (no backwards-compatible or non-backwards-compatible changes) as per the regular semver rules.

What we have introduced is the ability to make backwards-compatible changes on that patch version number "branch", by adding the _compatible to the label.  So, if backwards compatible changes were made in the revision from 3.2.0 to 3.2.1 then the version label becomes 3.2.1_compatible instead.  But 3.2.2 and 3.2.3 are also built on 3.2.1 and hence they must also have those same backwards-compatible changes relative to 3.2.0, so the rule is that once you have introduced the _compatible modifier then all subsequent patch versions must also use that modifier so we would end up with 3.2.0 => 3.2.1_compatible => 3.2.2 _compatible=> 3.2.3_compatible.  If a user compares version 3.2.3_compatible against 3.2.0 then the name indicates that it doesn't just include editorial changes but actual backwards compatible changes as well.

Very similar rules apply for non-backwards-compatible changes.  If we extend the example above and instead had a non-backwards-compatible between 3.2.1_compatible and 3.2.2_compatible, then we would end up with 3.2.2_non_compatible instead, and all subsequent patch versions would also have the _non_compatible marker.  So, the actual branch version history might look like: 3.2.0 => 3.2.1_compatible => 3.2.2 _non_compatible=> 3.2.3_non_compatible ... 3.2.x_non_compatible.  Again, if the user compares 3.2.3_non_compatible with 3.2.0 then they know that non-backwards-compatible changes have occurred.

Yes, this addition to Semver introduces some limited complexity, but as per my response to Deb, we felt that it was the only way to meet the various requirements.

Kind regards,
Rob


On 2 Jun 2026, at 18:32, Mike Bishop <[e-mail]> wrote:

That is... better. But that still suggests that 3.2.2_compatible doesn't necessarily include the diffs from 3.2.0 to 3.2.1, right?

As a comparison, consider Linux distros that modify upstream packages — they incorporate both the version of the upstream they're based on, plus a version number of their own changes applied on top. I suspect that's closer to the mental model most users will approach this with.

Restricting it to only the PATCH number helps, of course, but I still worry that you're creating a minefield of user expectations here. (And I think my comment further below about not "only updating" may reflect a related misunderstanding on my part.)

________________________________
From: Rob Wilton (rwilton) <[e-mail]<mailto:[e-mail]>>
Sent: Tuesday, June 2, 2026 12:43 PM
To: Mike Bishop <[e-mail]<mailto:[e-mail]>>
Cc: The IESG <[e-mail]<mailto:[e-mail]>>; [e-mail]<mailto:[e-mail]> <[e-mail]<mailto:[e-mail]>>; [e-mail]<mailto:[e-mail]> <[e-mail]<mailto:[e-mail]>>; [e-mail]<mailto:[e-mail]> <[e-mail]<mailto:[e-mail]>>; [e-mail]<mailto:[e-mail]> <[e-mail]<mailto:[e-mail]>>
Subject: Re: Mike Bishop's Discuss on draft-ietf-netmod-yang-semver-26: (with DISCUSS and COMMENT)

Hi Mike,

Please see one quick comment on the discuss inline ...

> On 2 Jun 2026, at 17:22, Mike Bishop via Datatracker <[e-mail]<mailto:[e-mail]>> wrote:
>
> 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.

We can look to see if we can word this better, but there can only be a single X.Y.Z version regardless of whether a version modifier is added to the end.  I.e., you are not allowed to have both versions "3.2.1" and "3.2.1_compatible".  If 3.2.1 already exists then the next version on the branch would be 3.2.2_compatible.  If 3.2.1_compatible already existed then the next version of the branch would be 3.2.2_compatible.

Kind regards,
Rob


>
> 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.
>
>
>