YANG Semantic Versioning

This section defines YANG Semantic Versioning, explains how it is used with YANG artifacts, and the rules associated with changing a artifact's semantic version number when its contents are updated.

YANG artifacts that employ semantic versioning MUST use a version string (e.g., in revision-label or as a package version) that corresponds to the following pattern: X.Y.Zv. Where: X, Y and Z are mandatory non-negative integers that are each less than 32768 and MUST NOT contain leading zeroes The '.' is a literal period (ASCII character 0x2e) v is an optional single character modifier that MUST be either 'm' or 'M' if it is specified Additionally, defines two specific types of metadata that may be appended to a semantic version string. Pre-release metadata MAY be appended to a semver string after a trailing '-' character. Build metadata MAY be appended after a trailing '+' character. If both pre-release and build metadata are present, then build metadata MUST follow pre-release metadata. These optional elements MUST be ignored by YANG semver parsers, but are allowed in order to support all of the rules. Thus, a version lineage that follows strict rules is allowed for a YANG artifact. Other version schemes MUST NOT use version strings that match this same pattern. For example, they may choose to use leading characters to distinguish themselves from YANG semver. A YANG module is defined in this document which contains single typedef that formally specifies this version pattern.

This document defines the YANG semantic versioning scheme that is used for YANG artifacts that employ the semver label. The versioning scheme has the following properties: The YANG semantic versioning scheme is extended from version 2.0.0 of the semantic versioning scheme defined at semver.org to cover the additional requirements for the management of YANG artifact lifecyles that cannot be addressed using the semver.org 2.0.0 versioning scheme alone. Unlike the versioning scheme, the YANG semantic versioning scheme supports limited updates to older versions of YANG artifacts, to allow for bug fixes and enhancements to artifact versions that are not the latest. However, it does not provide for the unlimited branching and updating of older revisions which are documented by the general rules in . YANG artifacts that follow the versioning scheme are fully compatible with implementations that understand the YANG semantic versioning scheme defined in this document. If updates are always restricted to the latest revision of the artifact only, then the version numbers used by the YANG semantic versioning scheme are exactly the same as those defined by the versioning scheme. Every YANG module versioned using the YANG semantic versioning scheme specifies the module's semantic version number as the argument to the 'rev:revision-label' statement. Because the rules put forth in are designed to work well with existing versions of YANG and allow for artifact authors to migrate to this scheme, it is not expected that all revisions of a given YANG artifact will have a semantic version label. For example, the first revision of a module may have been produced before this scheme was available. YANG packages that make use of this semantic versioning scheme will have their semantic version as the value of the "revision_label" property. As stated above, the YANG semver version number is expressed as a string of the form: 'X.Y.Zv'; where X, Y, and Z each represent non-negative integers smaller than 32768 without leading zeroes, and v represents an optional single character suffix: 'm' or 'M'. 'X' is the MAJOR version. Changes in the major version number indicate changes that are non-backwards-compatible to versions with a lower major version number. 'Y' is the MINOR version. Changes in the minor version number indicate changes that are backwards-compatible to versions with the same major version number, but a lower minor version number and no patch 'm' or 'M' modifier. 'Zv' is the PATCH version and modifier. Changes in the patch version number can indicate editorial, backwards-compatible, or non-backwards-compatible changes relative to versions with the same major and minor version numbers, but lower patch version number, depending on what form modifier 'v' takes: If the modifier letter is absent, the change represents an editorial change. An editorial change is defined to be a change in the YANG artifact's content that does not affect the semantic meaning or functionality provided by the artifact in any way. An example is correcting a spelling mistake in the description of a leaf within a YANG module. Note: restructuring how a module uses, or does not use, submodules is treated as an editorial level change on the condition that there is no change in the module's semantic behavior due to the restructuring. If, however, the modifier letter is present, the meaning is described below: 'm' - the change represents a backwards-compatible change 'M' - the change represents a non-backwards-compatible change The YANG articact name and YANG semantic version number uniquely identifies a revision of said artifact. There MUST NOT be multiple instances of a YANG artifact definition with the same name and YANG semantic version number but different content (and in the case of modules, different revision dates). There MUST NOT be multiple versions of a YANG artifact that have the same MAJOR, MINOR and PATCH version numbers, but different patch modifier letters. E.g., artifact version "1.2.3M" MUST NOT be defined if artifact version "1.2.3" has already been defined.

The following diagram and explanation illustrates how YANG semantic version numbers work.

Example YANG semantic version numbers for an example artifact: 0.1.0 | 0.2.0 | 1.0.0 | \ | 1.1.0 -> 1.1.1m -> 1.1.2M | | | 1.2.0 -> 1.2.1M -> 1.2.2M | | | 1.3.0 -> 1.3.1 | 2.0.0 | 3.0.0 \ 3.1.0 Assume the tree diagram above illustrates how an example YANG module's version history might evolve. For example, the tree might represent the following changes, listed in chronological order from oldest revision to newest: 0.1.0 - first beta module version 0.2.0 - second beta module version (with NBC changes) 1.0.0 - first release (may have NBC changes from 0.2.0) 1.1.0 - added new functionality, leaf "foo" (BC) 1.2.0 - added new functionality, leaf "baz" (BC) 1.3.0 - improve existing functionality, added leaf "foo-64" (BC) 1.3.1 - improve description wording for "foo-64" (Editorial) 1.1.1m - backport "foo-64" leaf to 1.1.x to avoid implementing "baz" from 1.2.0 (BC) 2.0.0 - change existing model for performance reasons, e.g. re-key list (NBC) 1.1.2M - NBC point bug fix, not required in 2.0.0 due to model changes (NBC) 3.0.0 - NBC bugfix, rename "baz" to "bar"; also add new BC leaf "wibble"; (NBC) 1.2.1M - backport NBC fix, changing "baz" to "bar" 1.2.2M - backport "wibble". This is a BC change but "M" modifier is sticky. 3.1.0 - introduce new leaf "wobble" (BC) The partial ordering relationships based on the semantic versioning numbers can be defined as follows: 1.0.0 < 1.1.0 < 1.2.0 < 1.3.0 < 2.0.0 < 3.0.0 < 3.1.0 1.0.0 < 1.1.0 < 1.1.1m < 1.1.2M 1.0.0 < 1.1.0 < 1.2.0 < 1.2.1M < 1.2.2M There is no ordering relationship between 1.1.1M and either 1.2.0 or 1.2.1M, except that they share the common ancestor of 1.1.0. Looking at the version number alone, the module definition in 2.0.0 does not necessarily contain the contents of 1.3.0. However, the module revision history in 2.0.0 may well indicate that it was edited from module version 1.3.0.

When a new revision of an artifact is produced, then the following rules define how the YANG semantic version number for the new artifact revision is calculated, based on the changes between the two artifact revisions, and the YANG semantic version number of the base artifact revision from which the changes are derived: If an artifact is being updated in a non-backwards-compatible way, then the artifact version "X.Y.Z[m|M]" MUST be updated to "X+1.0.0" unless that artifact version has already been defined with different content, in which case the artifact version "X.Y.Z+1M" MUST be used instead. If an artifact is being updated in a backwards-compatible way, then the next version number depends on the format of the current version number: "X.Y.Z" - the artifact version MUST be updated to "X.Y+1.0", unless that artifact version has already been defined with different content, when the artifact version MUST be updated to "X.Y.Z+1m" instead. "X.Y.Zm" - the artifact version MUST be updated to "X.Y.Z+1m". "X.Y.ZM" - the artifact version MUST be updated to "X.Y.Z+1M". If an artifact is being updated in an editorial way, then the next version number depends on the format of the current version number: "X.Y.Z" - the artifact version MUST be updated to "X.Y.Z+1" "X.Y.Zm" - the artifact version MUST be updated to "X.Y.Z+1m". "X.Y.ZM" - the artifact version MUST be updated to "X.Y.Z+1M". YANG artifact semantic version numbers beginning with 0, i.e "0.X.Y" are regarded as beta definitions and need not follow the rules above. Either the MINOR or PATCH version numbers may be updated, regardless of whether the changes are non-backwards-compatible, backwards-compatible, or editorial.

Below is a sample YANG module that uses the YANG semver revision label based on the rules defined in this document.

module yang-module-name { namespace "name-space"; prefix "prefix-name"; import ietf-yang-revisions { prefix "rev"; } description "to be completed"; revision 2018-02-28 { description "Added leaf 'wobble'"; rev:revision-label "3.1.0"; } revision 2017-12-31 { description "Rename 'baz' to 'bar', added leaf 'wibble'"; rev:revision-label "3.0.0"; rev:nbc-changes; } revision 2017-10-30 { description "Change the module structure"; rev:revision-label "2.0.0"; rev:nbc-changes; } revision 2017-08-30 { description "Clarified description of 'foo-64' leaf"; rev:revision-label "1.3.1"; } revision 2017-07-30 { description "Added leaf foo-64"; rev:revision-label "1.3.0"; } revision 2017-04-20 { description "Add new functionality, leaf 'baz'"; rev:revision-label "1.2.0"; } revision 2017-04-03 { description "Add new functionality, leaf 'foo'"; rev:revision-label "1.1.0"; } revision 2017-04-03 { description "First release version."; rev:revision-label "1.0.0"; } // Note: semver rules do not apply to 0.X.Y labels. revision 2017-01-30 { description "NBC changes to initial revision"; semver:module-version "0.2.0"; } revision 2017-01-26 { description "Initial module version"; semver:module-version "0.1.0"; } //YANG module definition starts here

Below is an example YANG package that uses the semver revision label based on the rules defined in this document.

{ "ietf-yang-instance-data:instance-data-set": { "name": "example-yang-pkg", "target-ptr": "TBD", "timestamp": "2018-09-06T17:00:00Z", "description": "Example IETF package definition", "content-data": { "ietf-yang-package:yang-package": { "name": "example-yang-pkg", "version": "1.3.1", ... }