Subject: [netmod] Proposed YANG semver revision-label guidelines (draft-ietf-netmod-yang-semver)

From: "Joe Clarke (jclarke)" <[email-masked]>
Date: Tue, 12 May 2020 19:55:57 +0000

There has been recent discussion about how to handle applying versions to new modules, modules in development, and revisions to modules that previously did not have a revision-label.  Below is proposed text to offer both general and IETF-specific guidelines for this.  The intent is to place this text in draft-ietf-netmod-yang-semver either as a new section 5 or a sub-section under section 3.  Before folding it in to the document, I wanted to get more WG eyes on this.

===

X. Guidelines for Module Development

When developing a brand new module using YANG semver as its revision-label scheme SHOULD begin using a 0 for the MAJOR version component.  This allows the module to disregard strict semver rules with respect to non-backwards-compatible changes during its initial development.  However, module developers MAY choose to use the semver pre-release syntax instead with a 1 for the MAJOR version component.  For example, an initial module revision-label might be 1.0.0-dev1.  If the authors choose to use the 0 MAJOR version component scheme, they MAY switch to the pre-release scheme with a MAJOR version component of 1 when the module is nearing initial release (e.g., a module's revision label may transition from 0.3.0 to 1.0.0-beta1 to indicate it is more mature and ready for testing).

When developing a new revision of an existing module using the YANG semver revision-label scheme, the intended target semver version MUST be used along with pre-release notation.  For example, if a released module which has a current revision-label of 1.0.0 is being modified and the intent is to make non-backwards-compatible changes, the first development MAJOR version component must be 2 with some pre-release notation such as -dev1, making the version 2.0.0-dev1.  That said, every publicly available release of a module MUST have a unique YANG semver revision-label.  Therefore, it may be prudent to include the year or year and month development began (e.g., 2.0.0-201907-dev1).  As a module undegoes development, it is possible that the original intent changes.  For example, a 1.0.0 version of a module that was destined to become 2.0.0 after a development cycle may have had a scope change such that the final version has no non-backwards-compatible changes and becomes 1.1.0 instead.  This change is acceptable to make during the development phase so long as pre-release notation is present in both versions (e.g., 2.0.0-dev3 becomes 1.1.0-alpha1).  However, on the next development cycle, if again the new target release is 2.0.0, new pre-release components must be used such that every revision-label for a given module MUST be unique throughout its entire lifecycle (e.g., the first pre-release version might be 2.0.0-202005-dev1 if keeping the same year and month notation mentioned above).

When an existing IETF module is being revised, it MUST use the target version for the revision-label with a pre-release string that includes the current RFC number plus the string "bis".  For example, if the module defined in RFCXXXX at version 1.0.0 is being revised to include non-backwards-compatible changes, its development revision-labels MUST include 2.0.0-XXXXbis.  Since they MUST also be unique, additional alphanumeric identifiers MUST be used (e.g., 2.0.0-XXXXbis-dev1).  Since each new bis will work off a new RFC number, this nomenclature ensures uniqueness for the module throughout its lifecycle.

If a module is being revised and the original module never had a revision-label (i.e., you wish to start using YANG semver in future module revisions), choose a semver value that makes the most sense based on the module's history.  For example, if a module started out in the pre-NMDA 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).  

===

Joe

---

From: Jan Lindblad <[email-masked]>
Date: Wed, 13 May 2020 16:04:26 +0200

Joe,

Thanks for sending this out to a wider audience. Sorry I missed the meeting yesterday. That particular time of week is very popular.

I think the text you propose below is good; I have no issues. For the record, I do have some issue relating to other pieces, especially around the use of the letter 'm'.

/jan

> On 12 May 2020, at 21:55, Joe Clarke (jclarke) <jclarke=[email-masked]> wrote:
> 
> When developing a new revision of an existing module using the YANG semver revision-label scheme, the intended target semver version MUST be used along with pre-release notation.  For example, if a released module which has a current revision-label of 1.0.0 is being modified and the intent is to make non-backwards-compatible changes, the first development MAJOR version component must be 2 with some pre-release notation such as -dev1, making the version 2.0.0-dev1.  That said, every publicly available release of a module MUST have a unique YANG semver revision-label.  Therefore, it may be prudent to include the year or year and month development began (e.g., 2.0.0-201907-dev1).  As a module undegoes development, it is possible that the original intent changes.  For example, a 1.0.0 version of a module that was destined to become 2.0.0 after a development cycle may have had a scope change such that the final version has no non-backwards-compatible changes and becomes 1.1.0 instead.  Th
> is change is acceptable to make during the development phase so long as pre-release notation is present in both versions (e.g., 2.0.0-dev3 becomes 1.1.0-alpha1).  However, on the next development cycle, if again the new target release is 2.0.0, new pre-release components must be used such that every revision-label for a given module MUST be unique throughout its entire lifecycle (e.g., the first pre-release version might be 2.0.0-202005-dev1 if keeping the same year and month notation mentioned above).
> 
> _______________________________________________
> netmod mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netmod
>

---

From: "Joe Clarke (jclarke)" <[email-masked]>
Date: Wed, 13 May 2020 14:45:09 +0000

> On May 13, 2020, at 10:04, Jan Lindblad <[email-masked]> wrote:
> 
> Joe,
> 

Thanks, Jan.  I missed the call yesterday, too, but I understand m|M is still being debated and there isn’t strong support of those letters specifically.

Joe

---

From: "Reshad Rahman (rrahman)" <[email-masked]>
Date: Wed, 13 May 2020 15:04:07 +0000

Jan, do you have an issue with the choice of the letter or its semantics? It has been mentioned that it's confusing to have 'm' and 'M'.

Regards,
Reshad.

On 2020-05-13, 10:45 AM, "netmod on behalf of Joe Clarke (jclarke)" <[email-masked] on behalf of jclarke=[email-masked]> wrote:

    
    
    Joe