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