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
