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

[Jan Lindblad <[e-mail]>]

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=[e-mail]> wrote:
> 
> 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.  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).
> 
> 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
> _______________________________________________
> netmod mailing list
> [e-mail]
> https://www.ietf.org/mailman/listinfo/netmod
>