Re: [netmod] YANG Versioning: Key Issues #2 and #3 - revision labels

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

I want to summarize what was presented at 118 in NETMOD, plus what was discussed on this week’s team call regarding these two key issues.


  *   We will remove the multiple revision-label schemes
  *   The revision-label concept will be removed from the module versioning draft and put into the YANG Semver draft as a [working name] ysver:version extension
  *   The argument to this extension will be a YANG Semver string
     *   YANG Semver is 100% compatible to SemVer 2.0.0 if there is no branching in the module development
     *   YANG Semver’s modifiers allow one to articulate a limited branching structure, needed by some vendors and SDOs

Joe

From: netmod <[e-mail]> on behalf of Jason Sterne (Nokia) <[e-mail]>
Date: Wednesday, July 19, 2023 at 17:19
To: [e-mail] <[e-mail]>
Subject: [netmod] YANG Versioning: Key Issues #2 and #3 - revision labels
Hi all,

The weekly call group thought it would be good to provide an advance look at Key Issues #2 and #3 before the IETF117 NETMOD meeting.

For now on the list let’s continue the focus on K1 but we’ll start in on K2 & K3 (if there is time) at IETF117.

Key Issue #2: Single v/s multiple revision label schemes
-------------------------------------------------------------------
Recap of revision-label-scheme:

-          Extension defined in YANG module versioning document.

-          Takes a mandatory parameter defining the scheme used, it is an identity derived from revision-label-scheme-base

-          Extension MUST be used if there is a revision label statement in the (sub)module

-          The YANG Semver document defines the scheme yang-semver
(note – the current YANG revision date is not considered a revision label / label scheme)


-          Example:

rev:revision-label-scheme "yangver:yang-semver";

Pros of revision-label-scheme:

-          YANG Semver deemed too restrictive by some

-          This provides flexibility to e.g. have vendor specific schemes which allow for infinite branching where the versions have no semantic meaning

-          Consistent framework for adding other schemes


Cons of revision-label-scheme

-          Flexibility comes with cost of added complexity, e.g. what if a module changes from scheme A to scheme B

-          YANG Semver is sufficient for IETF and many vendors

-          If some entity wants their own scheme they could just do it using their own separate extension (outside of any “framework”)

Impact of removing revision-label-scheme

-          We would rename revision-label e.g. to yangsemver-label

-          If a vendor wants a new versioning scheme, a proprietary extension would need to be added by that vendor (including augmentations of yang library, packages, etc)

-          The current IETF documents would be simpler

-          Cost/effort to make the changes to the documents


Key Issue #3: Why do we need YANG Semver (vs. SemVer 2.0.0)?
-------------------------------------------------------------------
SemVer 2.0.0:

-          Linear (no branching)

-          Simpler in construction

o   Major

o   Minor

o   Patch

-          1.0.0, 1.0.1, 1.1.0, 2.0.0, …

o   If a new feature is needed in 1.0.1, a 1.2.0 would need to be minted that incorporates the features of 1.1.0

-          Widely liked by the industry, but only works well when updating at the head (fine for open source, not acceptable for operators)

YANG Semver:

-          Support for limited branching (maintenance of released code)

-          Supports SemVer 2.0.0 rules

-          MAJOR.MINOR.PATCH_MODIFIER

o   _compatible

o   _non_compatible

Example:
1.0.0
    |
1.0.1 -- 1.0.2_non_compatible
    |
1.1.0
    |
2.0.0
A feature (or an NBC change can be backported)

Why YANG Semver:

-          Given that module versioning allows branching, the labeling scheme must also support branching

-          YANG Semver is a compromise between power and simplicity

o   Encourage “mostly” single track development with modifiers the exception

o   Retains support for some updates to older versions

-          Sufficient for  SDOs and vendors

-          Industry is familiar with Semver – tried to stay close to it

Jason (he/him)