> On May 13, 2020, at 10:04, Jan Lindblad <[email protected]> wrote: > > 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'.
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 > > /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
