draft-ietf-netmod-yang-semver-05.txt   draft-ietf-netmod-yang-semver-06.txt 
Network Working Group J. Clarke, Ed. Network Working Group J. Clarke, Ed.
Internet-Draft R. Wilton, Ed. Internet-Draft R. Wilton, Ed.
Updates: 8407 (if approved) Cisco Systems, Inc. Updates: 8407 (if approved) Cisco Systems, Inc.
Intended status: Standards Track R. Rahman Intended status: Standards Track R. Rahman
Expires: 12 May 2022 Expires: 3 June 2022
B. Lengyel B. Lengyel
Ericsson Ericsson
J. Sterne J. Sterne
Nokia Nokia
B. Claise B. Claise
Huawei Huawei
8 November 2021 30 November 2021
YANG Semantic Versioning YANG Semantic Versioning
draft-ietf-netmod-yang-semver-05 draft-ietf-netmod-yang-semver-06
Abstract Abstract
This document specifies a scheme and guidelines for applying an This document specifies a scheme and guidelines for applying an
extended set of semantic versioning rules to revisions of YANG extended set of semantic versioning rules to revisions of YANG
artifacts (e.g., modules and packages). Additionally, this document artifacts (e.g., modules and packages). Additionally, this document
defines an RFCAAAA-compliant revision-label-scheme for this YANG defines an RFCAAAA-compliant revision-label-scheme for this YANG
semantic versioning scheme. semantic versioning scheme.
Status of This Memo Status of This Memo
skipping to change at page 1, line 42 skipping to change at page 1, line 42
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on 12 May 2022. This Internet-Draft will expire on 3 June 2022.
Copyright Notice Copyright Notice
Copyright (c) 2021 IETF Trust and the persons identified as the Copyright (c) 2021 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/ Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document. license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights Please review these documents carefully, as they describe your rights
skipping to change at page 4, line 10 skipping to change at page 4, line 10
This section defines YANG Semantic Versioning, explains how it is This section defines YANG Semantic Versioning, explains how it is
used with YANG artifacts, and describes the rules associated with used with YANG artifacts, and describes the rules associated with
changing an artifact's semantic version when its contents are changing an artifact's semantic version when its contents are
updated. updated.
3.1. YANG Semver Pattern 3.1. YANG Semver Pattern
YANG artifacts that employ semantic versioning as defined in this YANG artifacts that employ semantic versioning as defined in this
document MUST use a version string (e.g., in revision-label or as a document MUST use a version string (e.g., in revision-label or as a
package version) that corresponds to the following pattern: package version) that corresponds to the following pattern:
X.Y.Z_COMPAT. Where: 'X.Y.Z_COMPAT'. Where:
* X, Y and Z are mandatory non-negative integers that are each less * X, Y and Z are mandatory non-negative integers that are each less
than or equal to 2147483647 (i.e., the maximum signed 32-bit than or equal to 2147483647 (i.e., the maximum signed 32-bit
integer value) and MUST NOT contain leading zeroes, integer value) and MUST NOT contain leading zeroes,
* The '.' is a literal period (ASCII character 0x2e), * The '.' is a literal period (ASCII character 0x2e),
* The '_' is an optional single literal underscore (ASCII character * The '_' is an optional single literal underscore (ASCII character
0x5f) and MUST only be present if the following COMPAT element is 0x5f) and MUST only be present if the following COMPAT element is
included, included,
skipping to change at page 5, line 44 skipping to change at page 5, line 44
with existing versions of YANG and allow for artifact authors to with existing versions of YANG and allow for artifact authors to
migrate to this scheme, it is not expected that all revisions of a migrate to this scheme, it is not expected that all revisions of a
given YANG artifact will have a semantic version label. For example, given YANG artifact will have a semantic version label. For example,
the first revision of a module or submodule may have been produced the first revision of a module or submodule may have been produced
before this scheme was available. before this scheme was available.
YANG packages that make use of this YANG Semver will reflect that in YANG packages that make use of this YANG Semver will reflect that in
the package metadata. the package metadata.
As stated above, the YANG semantic version is expressed as a string As stated above, the YANG semantic version is expressed as a string
of the form: 'X.Y.Z_COMPAT'; where X, Y, and Z each represent non- of the form: 'X.Y.Z_COMPAT'.
negative integers less than or equal to 2147483647 without leading
zeroes, and _COMPAT represents an optional suffix of either
"_compatible" or "_non_compatible".
* 'X' is the MAJOR version. Changes in the MAJOR version number * 'X' is the MAJOR version. Changes in the MAJOR version number
indicate changes that are non-backwards-compatible to versions indicate changes that are non-backwards-compatible to versions
with a lower MAJOR version number. with a lower MAJOR version number.
* 'Y' is the MINOR version. Changes in the MINOR version number * 'Y' is the MINOR version. Changes in the MINOR version number
indicate changes that are backwards-compatible to versions with indicate changes that are backwards-compatible to versions with
the same MAJOR version number, but a lower MINOR version number the same MAJOR version number, but a lower MINOR version number
and no PATCH "_compatible" or "_non_compatible" modifier. and no PATCH "_compatible" or "_non_compatible" modifier.
* 'Z_COMPAT' is the PATCH version and modifier. Changes in the * 'Z_COMPAT' is the PATCH version and modifier. Changes in the
PATCH version number can indicate editorial, backwards-compatible, PATCH version number can indicate editorial, backwards-compatible,
or non-backwards-compatible changes relative to versions with the or non-backwards-compatible changes relative to versions with the
same MAJOR and MINOR version numbers, but lower PATCH version same MAJOR and MINOR version numbers, but lower PATCH version
number, depending on what form modifier "_COMPAT" takes: number, depending on what form modifier '_COMPAT' takes:
- If the modifier string is absent, the change represents an - If the modifier string is absent, the change represents an
editorial change. An editorial change is defined to be a editorial change. An editorial change is defined to be a
change in the YANG artifact's content that does not affect the change in the YANG artifact's content that does not affect the
semantic meaning or functionality provided by the artifact in semantic meaning or functionality provided by the artifact in
any way. Some examples include correcting a spelling mistake any way. Some examples include correcting a spelling mistake
in the description of a leaf within a YANG module or submodule, in the description of a leaf within a YANG module or submodule,
non-significant whitespace changes (e.g., realigning non-significant whitespace changes (e.g., realigning
description statements or changing indendation), or changes to description statements or changing indendation), or changes to
YANG comments. Note: restructuring how a module uses, or does YANG comments. Note: restructuring how a module uses, or does
skipping to change at page 6, line 38 skipping to change at page 6, line 38
- If, however, the modifier string is present, the meaning is - If, however, the modifier string is present, the meaning is
described below: described below:
- "_compatible" - the change represents a backwards-compatible - "_compatible" - the change represents a backwards-compatible
change change
- "_non_compatible" - the change represents a non-backwards- - "_non_compatible" - the change represents a non-backwards-
compatible change compatible change
The '_COMPAT' modifier string is "sticky". Once a revision of a
module has a modifier in the revision label, then all descendants of
that revision with the same X.Y version digits will also have a
modifier. The modifier can change from "_compatible" to
"_non_compatible" in a descendant revision, but the modifier MUST NOT
change from "_non_compatible" to "_compatible" and MUST NOT be
removed. The persistence of the "_non_compatible" modifier ensures
that comparisions of revision labels do not give the false impression
of compatibility between two potentially non-compatible revisions.
If "_non_compatible" was removed, for example between revisions
"3.3.2_non_compatible" and "3.3.3" (where "3.3.3" was simply an
editorial change), then comparing revision labels of "3.3.3" back to
an ancestor "3.0.0" would look like they are backwards compatible
when they are not (since "3.3.2_non_compatible" was in the chain of
ancestors and introduced a non-backwards-compatible change).
The YANG artifact name and YANG semantic version uniquely identify a The YANG artifact name and YANG semantic version uniquely identify a
revision of said artifact. There MUST NOT be multiple instances of a revision of said artifact. There MUST NOT be multiple instances of a
YANG artifact definition with the same name and YANG semantic version YANG artifact definition with the same name and YANG semantic version
but different content (and in the case of modules and submodules, but different content (and in the case of modules and submodules,
different revision dates). different revision dates).
There MUST NOT be multiple versions of a YANG artifact that have the There MUST NOT be multiple versions of a YANG artifact that have the
same MAJOR, MINOR and PATCH version numbers, but different patch same MAJOR, MINOR and PATCH version numbers, but different patch
modifier strings. E.g., artifact version "1.2.3_non_compatible" MUST modifier strings. E.g., artifact version "1.2.3_non_compatible" MUST
NOT be defined if artifact version "1.2.3" has already been defined. NOT be defined if artifact version "1.2.3" has already been defined.
skipping to change at page 9, line 34 skipping to change at page 9, line 34
1.0.0 < 1.1.0 < 1.1.1_compatible < 1.1.2_non_compatible 1.0.0 < 1.1.0 < 1.1.1_compatible < 1.1.2_non_compatible
1.0.0 < 1.1.0 < 1.2.0 < 1.2.1_non_compatible < 1.0.0 < 1.1.0 < 1.2.0 < 1.2.1_non_compatible <
1.2.2_non_compatible 1.2.2_non_compatible
1.0.0 < 1.1.0 < 1.2.0 < 1.3.0 < 1.3.1_non_compatible 1.0.0 < 1.1.0 < 1.2.0 < 1.3.0 < 1.3.1_non_compatible
1.0.0 < 1.1.0 < 1.2.0 < 1.3.0 < 1.4.0 1.0.0 < 1.1.0 < 1.2.0 < 1.3.0 < 1.4.0
There is no ordering relationship between 1.1.1_non_compatible and There is no ordering relationship between "1.1.1_non_compatible" and
either 1.2.0 or 1.2.1_non_compatible, except that they share the either "1.2.0" or "1.2.1_non_compatible", except that they share the
common ancestor of 1.1.0. common ancestor of "1.1.0".
Looking at the version number alone does not indicate ancestry. The Looking at the version number alone does not indicate ancestry. The
module definition in 2.0.0, for example, does not contain all the module definition in "2.0.0", for example, does not contain all the
contents of 1.3.0. Version 2.0.0 is not derived from 1.3.0. contents of "1.3.0". Version "2.0.0" is not derived from "1.3.0".
3.3. YANG Semantic Version Update Rules 3.3. YANG Semantic Version Update Rules
When a new revision of an artifact is produced, then the following When a new revision of an artifact is produced, then the following
rules define how the YANG semantic version for the new artifact rules define how the YANG semantic version for the new artifact
revision is calculated, based on the changes between the two artifact revision is calculated, based on the changes between the two artifact
revisions, and the YANG semantic version of the base artifact revisions, and the YANG semantic version of the base artifact
revision from which the changes are derived. revision from which the changes are derived.
The following four rules specify the RECOMMENDED, and REQUIRED The following four rules specify the RECOMMENDED, and REQUIRED
skipping to change at page 10, line 19 skipping to change at page 10, line 19
artifact but with different content, in which case the artifact artifact but with different content, in which case the artifact
version "X.Y.Z+1_non_compatible" SHOULD be used instead. version "X.Y.Z+1_non_compatible" SHOULD be used instead.
2. If an artifact is being updated in a backwards-compatible way, 2. If an artifact is being updated in a backwards-compatible way,
then the next version number depends on the format of the current then the next version number depends on the format of the current
version number: version number:
i "X.Y.Z" - the artifact version SHOULD be updated to i "X.Y.Z" - the artifact version SHOULD be updated to
"X.Y+1.0", unless that version has already been used for "X.Y+1.0", unless that version has already been used for
this artifact but with different content, when the artifact this artifact but with different content, when the artifact
version SHOULD be updated to "X.Y.Z+1_compatible"" instead. version SHOULD be updated to "X.Y.Z+1_compatible" instead.
ii "X.Y.Z_compatible" - the artifact version SHOULD be updated ii "X.Y.Z_compatible" - the artifact version SHOULD be updated
to "X.Y.Z+1_compatible". to "X.Y.Z+1_compatible".
iii "X.Y.Z_non_compatible" - the artifact version SHOULD be iii "X.Y.Z_non_compatible" - the artifact version SHOULD be
updated to "X.Y.Z+1_non_compatible". updated to "X.Y.Z+1_non_compatible".
3. If an artifact is being updated in an editorial way, then the 3. If an artifact is being updated in an editorial way, then the
next version number depends on the format of the current version next version number depends on the format of the current version
number: number:
skipping to change at page 14, line 8 skipping to change at page 14, line 8
its revision history may be used to satisfy the import requirement. its revision history may be used to satisfy the import requirement.
For example: For example:
import example-module { import example-module {
rev:revision-or-derived 3.0.0; rev:revision-or-derived 3.0.0;
} }
Note: the import lookup does not stop when a non-backward-compatible Note: the import lookup does not stop when a non-backward-compatible
change is encountered. That is, if module B imports a module A at or change is encountered. That is, if module B imports a module A at or
derived from version 2.0.0, resolving that import will pass through a derived from version 2.0.0, resolving that import will pass through a
revision of module A with version 2.1.0_non_compatible in order to revision of module A with version "2.1.0_non_compatible" in order to
determine if the present instance of module A derives from 2.0.0. determine if the present instance of module A derives from "2.0.0".
If an import by revision-or-derived cannot locate the specified If an import by revision-or-derived cannot locate the specified
revision-label in a given module's revision history, that import will revision-label in a given module's revision history, that import will
fail. This is noted in the case of version gaps. That is, if a fail. This is noted in the case of version gaps. That is, if a
module's history includes 1.0.0, 1.1.0, and 1.3.0, an import from module's history includes "1.0.0", "1.1.0", and "1.3.0", an import
revision-or-derived at 1.2.0 will be unable to locate the specified from revision-or-derived at "1.2.0" will be unable to locate the
revision entry and thus the import cannot be satisfied. specified revision entry and thus the import cannot be satisfied.
5. Guidelines for Using Semver During Module Development 5. Guidelines for Using Semver During Module Development
This section and the IETF-specific sub-section below provides YANG This section and the IETF-specific sub-section below provides YANG
Semver-specific guidelines to consider when developing new YANG Semver-specific guidelines to consider when developing new YANG
modules. As such this section updates [RFC8407] . modules. As such this section updates [RFC8407] .
Development of a brand new YANG module or submodule outside of the Development of a brand new YANG module or submodule outside of the
IETF that uses YANG Semver as its revision-label scheme SHOULD begin IETF that uses YANG Semver as its revision-label scheme SHOULD begin
with a 0 for the MAJOR version component. This allows the module or with a 0 for the MAJOR version component. This allows the module or
skipping to change at page 22, line 5 skipping to change at page 22, line 5
[RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of [RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of
Documents Containing YANG Data Models", BCP 216, RFC 8407, Documents Containing YANG Data Models", BCP 216, RFC 8407,
DOI 10.17487/RFC8407, October 2018, DOI 10.17487/RFC8407, October 2018,
<https://www.rfc-editor.org/info/rfc8407>. <https://www.rfc-editor.org/info/rfc8407>.
[I-D.ietf-netmod-yang-module-versioning] [I-D.ietf-netmod-yang-module-versioning]
Wilton, R., Rahman, R., Lengyel, B., Clarke, J., and J. Wilton, R., Rahman, R., Lengyel, B., Clarke, J., and J.
Sterne, "Updated YANG Module Revision Handling", Work in Sterne, "Updated YANG Module Revision Handling", Work in
Progress, Internet-Draft, draft-ietf-netmod-yang-module- Progress, Internet-Draft, draft-ietf-netmod-yang-module-
versioning-04, 25 October 2021, versioning-05, 8 November 2021,
<https://tools.ietf.org/html/draft-ietf-netmod-yang- <https://tools.ietf.org/html/draft-ietf-netmod-yang-
module-versioning-04>. module-versioning-05>.
10.2. Informative References 10.2. Informative References
[I-D.clacla-netmod-yang-model-update] [I-D.clacla-netmod-yang-model-update]
Claise, B., Clarke, J., Lengyel, B., and K. D'Souza, "New Claise, B., Clarke, J., Lengyel, B., and K. D'Souza, "New
YANG Module Update Procedure", Work in Progress, Internet- YANG Module Update Procedure", Work in Progress, Internet-
Draft, draft-clacla-netmod-yang-model-update-06, 2 July Draft, draft-clacla-netmod-yang-model-update-06, 2 July
2018, <https://tools.ietf.org/html/draft-clacla-netmod- 2018, <https://tools.ietf.org/html/draft-clacla-netmod-
yang-model-update-06>. yang-model-update-06>.
 End of changes. 15 change blocks. 
23 lines changed or deleted 36 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/