< draft-ietf-netmod-yang-semver-02.txt		draft-ietf-netmod-yang-semver-03.txt >
	Network Working Group B. Claise		Network Working Group B. Claise
	Internet-Draft Huawei		Internet-Draft Huawei
	Updates: 8407 (if approved) J. Clarke, Ed.		Updates: 8407 (if approved) J. Clarke, Ed.
	Intended status: Standards Track R. Rahman		Intended status: Standards Track R. Rahman
	Expires: 25 August 2021 R. Wilton, Ed.		Expires: 13 January 2022 R. Wilton, Ed.
	Cisco Systems, Inc.		Cisco Systems, Inc.
	B. Lengyel		B. Lengyel
	Ericsson		Ericsson
	J. Sterne		J. Sterne
	Nokia		Nokia
	K. D'Souza		K. D'Souza
	AT&T		AT&T
	21 February 2021		12 July 2021
	YANG Semantic Versioning		YANG Semantic Versioning
	draft-ietf-netmod-yang-semver-02		draft-ietf-netmod-yang-semver-03
	Abstract		Abstract
	This document specifies a scheme and guidelines for applying a		This document specifies a scheme and guidelines for applying a
	modified set of semantic versioning rules to revisions of YANG		modified set of semantic versioning rules to revisions of YANG
	modules. Additionally, this document defines a revision-label for		modules. Additionally, this document defines a revision-label for
	this modified semver scheme.		this modified semver 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 25 August 2021.		This Internet-Draft will expire on 13 January 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 2, line 23 ¶		skipping to change at page 2, line 23 ¶
	Table of Contents		Table of Contents
	1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2		1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
	2. Terminology and Conventions . . . . . . . . . . . . . . . . . 3		2. Terminology and Conventions . . . . . . . . . . . . . . . . . 3
	3. YANG Semantic Versioning . . . . . . . . . . . . . . . . . . 3		3. YANG Semantic Versioning . . . . . . . . . . . . . . . . . . 3
	3.1. YANG Semantic Versioning Pattern . . . . . . . . . . . . 3		3.1. YANG Semantic Versioning Pattern . . . . . . . . . . . . 3
	3.2. Semantic Versioning Scheme for YANG Artifacts . . . . . . 4		3.2. Semantic Versioning Scheme for YANG Artifacts . . . . . . 4
	3.2.1. Examples for YANG semantic version numbers . . . . . 6		3.2.1. Examples for YANG semantic version numbers . . . . . 6
	3.3. YANG Semantic Version Update Rules . . . . . . . . . . . 8		3.3. YANG Semantic Version Update Rules . . . . . . . . . . . 8
	3.4. Examples of the YANG Semver Label . . . . . . . . . . . . 9		3.4. Examples of the YANG Semver Label . . . . . . . . . . . . 10
	3.4.1. Example Module Using YANG Semver . . . . . . . . . . 9		3.4.1. Example Module Using YANG Semver . . . . . . . . . . 10
	3.4.2. Example of Package Using YANG Semver . . . . . . . . 11		3.4.2. Example of Package Using YANG Semver . . . . . . . . 12
	4. Import Module by Semantic Version . . . . . . . . . . . . . . 11		4. Import Module by Semantic Version . . . . . . . . . . . . . . 12
	5. Guidelines for Using Semver During Module Development . . . . 12		5. Guidelines for Using Semver During Module Development . . . . 13
	5.1. Pre-release Version Precedence . . . . . . . . . . . . . 13		5.1. Pre-release Version Precedence . . . . . . . . . . . . . 14
	5.2. YANG Semver in IETF Modules . . . . . . . . . . . . . . . 13		5.2. YANG Semver in IETF Modules . . . . . . . . . . . . . . . 15
	6. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 14		6. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 16
	7. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 16		7. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 17
	8. Security Considerations . . . . . . . . . . . . . . . . . . . 17		8. Security Considerations . . . . . . . . . . . . . . . . . . . 18
	9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17		9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18
	9.1. YANG Module Registrations . . . . . . . . . . . . . . . . 17		9.1. YANG Module Registrations . . . . . . . . . . . . . . . . 18
	9.2. Guidance for YANG Semver in IANA maintained YANG		9.2. Guidance for YANG Semver in IANA maintained YANG modules
	modules . . . . . . . . . . . . . . . . . . . . . . . . . 17		and submodules . . . . . . . . . . . . . . . . . . . . . 19
	10. References . . . . . . . . . . . . . . . . . . . . . . . . . 18		10. References . . . . . . . . . . . . . . . . . . . . . . . . . 19
	10.1. Normative References . . . . . . . . . . . . . . . . . . 18		10.1. Normative References . . . . . . . . . . . . . . . . . . 19
	10.2. Informative References . . . . . . . . . . . . . . . . . 18		10.2. Informative References . . . . . . . . . . . . . . . . . 20
	Appendix A. Example IETF Module Development . . . . . . . . . . 19		Appendix A. Example IETF Module Development . . . . . . . . . . 21
	Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 21		Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 22
	1. Introduction		1. Introduction
	[I-D.ietf-netmod-yang-module-versioning] puts forth a number of		[I-D.ietf-netmod-yang-module-versioning] puts forth a number of
	concepts relating to modified rules for updating modules, a means to		concepts relating to modified rules for updating modules and
	signal when a new revision of a module has non-backwards-compatible		submodules, a means to signal when a new revision of a module or
	(NBC) changes compared to its previous revision, and a versioning		submodule has non-backwards-compatible (NBC) changes compared to its
	scheme that uses the revision history as a lineage for determining		previous revision, and a versioning scheme that uses the revision
	from where a specific revision of a YANG module is derived.		history as a lineage for determining from where a specific revision
	Additionally, section 3.3 of [I-D.ietf-netmod-yang-module-versioning]		of a YANG module or submodule is derived. Additionally, section 3.3
	defines a revision label which can be used as an overlay or alias to		of [I-D.ietf-netmod-yang-module-versioning] defines a revision label
	provide additional context or an additional way to refer to a		which can be used as an overlay or alias to provide additional
	specific revision.		context or an additional way to refer to a specific revision.
	This document defines a revision-label scheme that uses modified		This document defines a revision-label scheme that uses modified
	[semver] rules for YANG artifacts (i.e., YANG modules and YANG		[semver] rules for YANG artifacts (i.e., YANG modules, YANG
	packages [I-D.ietf-netmod-yang-packages] ) as well as the revision		submodules, and YANG packages [I-D.ietf-netmod-yang-packages] ) as
	label definition for using this scheme. The goal of this is to add a		well as the revision label definition for using this scheme. The
	human readable version label that provides compatibility information		goal of this is to add a human readable version label that provides
	for the YANG artifact without one needing to compare or parse its		compatibility information for the YANG artifact without one needing
	body. The label and rules defined herein represent the RECOMMENDED		to compare or parse its body. The label and rules defined herein
	revision label scheme for IETF YANG artifacts.		represent the RECOMMENDED revision label scheme for IETF YANG
			artifacts.
			Note that a specific revision of the Semver 2.0.0 specification is
			referenced here (from June 19, 2020) to provide an immutable version.
			This is because the 2.0.0 version of the specification has changed
			over time without any change to the semantic version itself. In some
			cases the text has changed in non-backwards-compatible ways.
	2. Terminology and Conventions		2. Terminology and Conventions
	The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",		The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
	"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and		"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
	"OPTIONAL" in this document are to be interpreted as described in BCP		"OPTIONAL" in this document are to be interpreted as described in BCP
	14 [RFC2119] [RFC8174] when, and only when, they appear in all		14 [RFC2119] [RFC8174] when, and only when, they appear in all
	capitals, as shown here.		capitals, as shown here.
	Additionally, this document uses the following terminology:		Additionally, this document uses the following terminology:
	* YANG artifact: YANG modules, YANG packages		* YANG artifact: YANG modules, YANG submodules, and YANG packages
	[I-D.ietf-netmod-yang-packages] , and YANG schema elements are		[I-D.ietf-netmod-yang-packages] , and YANG schema elements are
	examples of YANG artifacts for the purposes of this document.		examples of YANG artifacts for the purposes of this document.
	3. YANG Semantic Versioning		3. YANG Semantic Versioning
	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 the rules associated with changing an		used with YANG artifacts, and the rules associated with changing an
	artifact's semantic version number when its contents are updated.		artifact's semantic version number when its contents are updated.
	3.1. YANG Semantic Versioning Pattern		3.1. YANG Semantic Versioning Pattern
	skipping to change at page 4, line 15 ¶		skipping to change at page 4, line 25 ¶
	* COMPAT, if it is specified, MUST be either the literal string		* COMPAT, if it is specified, MUST be either the literal string
	"compatible" or the literal string "non_compatible"		"compatible" or the literal string "non_compatible"
	Additionally, [semver] defines two specific types of metadata that		Additionally, [semver] defines two specific types of metadata that
	may be appended to a semantic version string. Pre-release metadata		may be appended to a semantic version string. Pre-release metadata
	MAY be appended to a semver string after a trailing '-' character.		MAY be appended to a semver string after a trailing '-' character.
	Build metadata MAY be appended after a trailing '+' character. If		Build metadata MAY be appended after a trailing '+' character. If
	both pre-release and build metadata are present, then build metadata		both pre-release and build metadata are present, then build metadata
	MUST follow pre-release metadata. While build metadata MUST be		MUST follow pre-release metadata. While build metadata MUST be
	ignored by YANG semver parsers, pre-release metadata MUST be used		ignored by YANG semver parsers, pre-release metadata MUST be used
	during module development and MUST be considered base on Section 5 .		during module and submodule development and MUST be considered base
	Both pre-release and build metadata are allowed in order to support		on Section 5 . Both pre-release and build metadata are allowed in
	all of the [semver] rules. Thus, a version lineage that follows		order to support all of the [semver] rules. Thus, a version lineage
	strict [semver] rules is allowed for a YANG artifact.		that follows strict [semver] rules is allowed for a YANG artifact.
	To signal the use of this versioning scheme, modules MUST set the		To signal the use of this versioning scheme, modules and submodules
	revision-label-scheme extension as defined in		MUST set the revision-label-scheme extension as defined in
	[I-D.ietf-netmod-yang-module-versioning] to the identity "yang-		[I-D.ietf-netmod-yang-module-versioning] to the identity "yang-
	semver". That identity value is defined in the ietf-yang-semver		semver". That identity value is defined in the ietf-yang-semver
	module below.		module below.
	Additionally, this ietf-yang-semver module defines a typedef that		Additionally, this ietf-yang-semver module defines a typedef that
	formally specifies the syntax of the YANG semver version string.		formally specifies the syntax of the YANG semver version string.
	3.2. Semantic Versioning Scheme for YANG Artifacts		3.2. Semantic Versioning Scheme for YANG Artifacts
	This document defines the YANG semantic versioning scheme that is		This document defines the YANG semantic versioning scheme that is
	skipping to change at page 5, line 10 ¶		skipping to change at page 5, line 22 ¶
	* YANG artifacts that follow the [semver] versioning scheme are		* YANG artifacts that follow the [semver] versioning scheme are
	fully compatible with implementations that understand the YANG		fully compatible with implementations that understand the YANG
	semantic versioning scheme defined in this document.		semantic versioning scheme defined in this document.
	* If updates are always restricted to the latest revision of the		* If updates are always restricted to the latest revision of the
	artifact only, then the version numbers used by the YANG semantic		artifact only, then the version numbers used by the YANG semantic
	versioning scheme are exactly the same as those defined by the		versioning scheme are exactly the same as those defined by the
	[semver] versioning scheme.		[semver] versioning scheme.
	Every YANG module versioned using the YANG semantic versioning scheme		Every YANG module and submodule versioned using the YANG semantic
	specifies the module's semantic version number as the argument to the		versioning scheme specifies the module's or submodule's semantic
	'rev:revision-label' statement.		version number as the argument to the 'rev:revision-label' statement.
	Because the rules put forth in		Because the rules put forth in
	[I-D.ietf-netmod-yang-module-versioning] are designed to work well		[I-D.ietf-netmod-yang-module-versioning] are designed to work well
	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 may have been produced before this		the first revision of a module or submodule may have been produced
	scheme was available.		before this scheme was available.
	YANG packages that make use of this semantic versioning scheme will		YANG packages that make use of this semantic versioning scheme will
	have their semantic version as the value of the "revision_label"		have their semantic version as the value of the "revision_label"
	property.		property.
	As stated above, the YANG semver version number is expressed as a		As stated above, the YANG semver version number is expressed as a
	string of the form: 'X.Y.Z_COMPAT'; where X, Y, and Z each represent		string of the form: 'X.Y.Z_COMPAT'; where X, Y, and Z each represent
	non-negative integers smaller than 2147483647 without leading zeroes,		non-negative integers smaller than 2147483647 without leading zeroes,
	and _COMPAT represents an optional suffix of either "_compatible" or		and _COMPAT represents an optional suffix of either "_compatible" or
	"_non_compatible".		"_non_compatible".
	skipping to change at page 5, line 52 ¶		skipping to change at page 6, line 16 ¶
	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, non-		in the description of a leaf within a YANG module or submodule,
	significant whitespace changes (e.g. realigning description		non-significant whitespace changes (e.g. realigning
	statements, or changing indendation), or changes to YANG		description statements, or changing indendation), or changes to
	comments. Note: restructuring how a module uses, or does not		YANG comments. Note: restructuring how a module uses, or does
	use, submodules is treated as an editorial level change on the		not use, submodules is treated as an editorial level change on
	condition that there is no change in the module's semantic		the condition that there is no change in the module's semantic
	behavior due to the restructuring.		behavior due to the restructuring.
	- 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 YANG artifact name and YANG semantic version number uniquely		The YANG artifact name and YANG semantic version number uniquely
	identify a revision of said artifact. There MUST NOT be multiple		identify a revision of said artifact. There MUST NOT be multiple
	instances of a YANG artifact definition with the same name and YANG		instances of a YANG artifact definition with the same name and YANG
	semantic version number but different content (and in the case of		semantic version number but different content (and in the case of
	modules, different revision dates).		modules and submodules, 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.
	3.2.1. Examples for YANG semantic version numbers		3.2.1. Examples for YANG semantic version numbers
	The following diagram and explanation illustrates how YANG semantic		The following diagram and explanation illustrates how YANG semantic
	version numbers work.		version numbers work.
	skipping to change at page 8, line 36 ¶		skipping to change at page 8, line 36 ¶
	does not necessarily contain the contents of 1.3.0. However, the		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		module revision history in 2.0.0 may well indicate that it was edited
	from module version 1.3.0.		from module version 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 number for the new		rules define how the YANG semantic version number 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 number of the base		artifact revisions, and the YANG semantic version number of the base
	artifact revision from which the changes are derived:		artifact revision from which the changes are derived.
			The following four rules specify the RECOMMENDED, and REQUIRED
			minimum, update to a YANG semantic version number:
	1. If an artifact is being updated in a non-backwards-compatible		1. If an artifact is being updated in a non-backwards-compatible
	way, then the artifact version		way, then the artifact version
	"X.Y.Z[_compatible|_non_compatible]" MUST be updated to "X+1.0.0"		"X.Y.Z[_compatible|_non_compatible]" SHOULD be updated to
	unless that artifact version has already been defined with		"X+1.0.0" unless that version has already been used for this
	different content, in which case the artifact version		artifact but with different content, in which case the artifact
	"X.Y.Z+1_non_compatible" MUST be used instead.		version "X.Y.Z+1_non_compatible" SHOULD be used instead.
	2. Under some circumstances (e.g., to avoid adding a "_compatible"
	modifier) an artifact author MAY also update the MAJOR version
	when the only changes are backwards-compatible. This is where
	tooling is important to highlight all changes. Because, while
	avoiding the "_compatible" and "_non_compatible" modifiers have a
	clear advantage, bumping a MAJOR version when changes are
	entirely backwards-compatible may confuse end users.
	3. An artifact author MAY choose to skip version numbers. That is,
	an artifact's revision history can include 1.0.0, 1.1.0, and
	1.3.0 where 1.2.0 is skipped. Note that doing so has an impact
	when importing modules by revision-or-derived. See Section 4 for
	more details on importing modules with revision-label version
	gaps.
	4. 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 MUST be updated to "X.Y+1.0",		i "X.Y.Z" - the artifact version SHOULD be updated to
	unless that artifact version has already been defined with		"X.Y+1.0", unless that version has already been used for
	different content, when the artifact version MUST be updated		this artifact but with different content, when the artifact
	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 MUST be updated to		ii "X.Y.Z_compatible" - the artifact version SHOULD be updated
	"X.Y.Z+1_compatible".		to "X.Y.Z+1_compatible".
	iii "X.Y.Z_non_compatible" - the artifact version MUST 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".
	5. 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:
	i "X.Y.Z" - the artifact version MUST be updated to "X.Y.Z+1"		i "X.Y.Z" - the artifact version SHOULD be updated to
			"X.Y.Z+1"
	ii "X.Y.Z_compatible" - the artifact version MUST be updated to		ii "X.Y.Z_compatible" - the artifact version SHOULD be updated
	"X.Y.Z+1_compatible".		to "X.Y.Z+1_compatible".
	iii "X.Y.Z_non_compatible" - the artifact version MUST 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".
	6. YANG artifact semantic version numbers beginning with 0, i.e		4. YANG artifact semantic version numbers beginning with 0, i.e.,
	"0.X.Y" are regarded as beta definitions and need not follow the		"0.X.Y", are regarded as beta definitions and need not follow the
	rules above. Either the MINOR or PATCH version numbers may be		rules above. Either the MINOR or PATCH version numbers may be
	updated, regardless of whether the changes are non-backwards-		updated, regardless of whether the changes are non-backwards-
	compatible, backwards-compatible, or editorial. See Section 5		compatible, backwards-compatible, or editorial. See Section 5
	for more details on using this notation during module		for more details on using this notation during module and
	development.		submodule development.
			5. XXX - Add some text about pre-release labels, or perhaps as a
			rule 5 above.
			Although artifacts SHOULD be updated according to the rules above,
			which specify the recommended (and minimum required) update to the
			version number, the following rules MAY be applied when choosing a
			new version number:
			1. An artifact author MAY update the version number with a more
			significant update than described by the rules above. For
			example, an artifact could be given a new MAJOR version number
			(i.e., X+1.0.0), even though no non-backwards-compatible changes
			have occurred, or an artifact could be given a new MINOR version
			number (i.e., X.Y+1.0) even if the changes were only editorial.
			2. An artifact author MAY skip version numbers. That is, an
			artifact's revision history could be 1.0.0, 1.1.0, and 1.3.0
			where 1.2.0 is skipped. Note that skipping versions has an
			impact when importing modules by revision-or-derived. See
			Section 4 for more details on importing modules with revision-
			label version gaps.
			Although YANG Semver always indicates when a non-backwards-
			compatible, or backwards-compatible change may have occurred to a
			YANG artifact, it does not guarantee that such a change has occurred,
			or that consumers of that YANG artifact will be impacted by the
			change. Hence, tooling, e.g.,
			[I-D.ietf-netmod-yang-schema-comparison] , also plays an important
			role for comparing YANG artifacts and calculating the likely impact
			from changes.
			[I-D.ietf-netmod-yang-module-versioning] defines the "rev:nbc-
			changes" extension statement to indicate where non-backwards-
			compatible changes have occurred in the module revision history. If
			a revision entry in a module's revision history includes the
			"rev:nbc-changes" statement then that MUST be reflected in any YANG
			Semver version associated with that revision. However, the reverse
			does not necessarily hold, i.e., if the MAJOR version has been
			incremented it does not necessarily mean that a "rev:nbc-changes"
			statement would be present.
	3.4. Examples of the YANG Semver Label		3.4. Examples of the YANG Semver Label
	3.4.1. Example Module Using YANG Semver		3.4.1. Example Module Using YANG Semver
	Below is a sample YANG module that uses the YANG semver revision		Below is a sample YANG module that uses the YANG semver revision
	label based on the rules defined in this document.		label based on the rules defined in this document.
	module example-versioned-module {		module example-versioned-module {
	yang-version 1.1;		yang-version 1.1;
	skipping to change at page 11, line 48 ¶		skipping to change at page 12, line 34 ¶
	...		...
	}		}
	4. Import Module by Semantic Version		4. Import Module by Semantic Version
	[I-D.ietf-netmod-yang-module-versioning] allows for imports to be		[I-D.ietf-netmod-yang-module-versioning] allows for imports to be
	done based on a module or a derived revision of a module. The		done based on a module or a derived revision of a module. The
	rev:revision-or-derived statement can specify either a revision date		rev:revision-or-derived statement can specify either a revision date
	or a revision label. When importing by semver, the YANG semver		or a revision label. When importing by semver, the YANG semver
	revision label value MAY be used as an argument to rev:revision-or-		revision label value MAY be used as an argument to rev:revision-or-
	derived. In so, any module which has that semver label as its latest		derived. When used as such, any module which has that semver label
	revision label or has that label in its revision history can be used		as its latest revision label or has that label in its revision
	to satisfy the import requirement. For example:		history can be used to satisfy the import requirement. 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.
	skipping to change at page 12, line 28 ¶		skipping to change at page 13, line 18 ¶
	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 from
	revision-or-derived at 1.2.0 will be unable to locate the specified		revision-or-derived at 1.2.0 will be unable to locate the specified
	revision entry and thus the import cannot be satisfied.		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 outside of the IETF that uses		Development of a brand new YANG module or submodule outside of the
	YANG semver as its revision-label scheme SHOULD begin with a 0 for		IETF that uses YANG semver as its revision-label scheme SHOULD begin
	the MAJOR version component. This allows the module to disregard		with a 0 for the MAJOR version component. This allows the module or
	strict semver rules with respect to non-backwards-compatible changes		submodule to disregard strict semver rules with respect to non-
	during its initial development. However, module developers MAY		backwards-compatible changes during its initial development.
	choose to use the semver pre-release syntax instead with a 1 for the		However, module or submodule developers MAY choose to use the semver
	MAJOR version component. For example, an initial module revision-		pre-release syntax instead with a 1 for the MAJOR version component.
	label might be either 0.0.1 or 1.0.0-alpha.1. If the authors choose		For example, an initial module or submodule revision-label might be
	to use the 0 MAJOR version component scheme, they MAY switch to the		either 0.0.1 or 1.0.0-alpha.1. If the authors choose to use the 0
	pre-release scheme with a MAJOR version component of 1 when the		MAJOR version component scheme, they MAY switch to the pre-release
	module is nearing initial release (e.g., a module's revision label		scheme with a MAJOR version component of 1 when the module or
	may transition from 0.3.0 to 1.0.0-beta.1 to indicate it is more		submodule is nearing initial release (e.g., a module's or submodule's
	mature and ready for testing).		revision label may transition from 0.3.0 to 1.0.0-beta.1 to indicate
			it is more mature and ready for testing).
	When using pre-release notation, the format MUST include at least one		When using pre-release notation, the format MUST include at least one
	alphabetic component and MUST end with a '.' and then one or more		alphabetic component and MUST end with a '.' and then one or more
	digits. These alphanumeric components will be used when deciding		digits. These alphanumeric components will be used when deciding
	pre-release precedence. The following are examples of valid pre-		pre-release precedence. The following are examples of valid pre-
	release versions		release versions
	1.0.0-alpha.1		1.0.0-alpha.1
	1.0.0-alpha.3		1.0.0-alpha.3
	skipping to change at page 13, line 4 ¶		skipping to change at page 13, line 44 ¶
	alphabetic component and MUST end with a '.' and then one or more		alphabetic component and MUST end with a '.' and then one or more
	digits. These alphanumeric components will be used when deciding		digits. These alphanumeric components will be used when deciding
	pre-release precedence. The following are examples of valid pre-		pre-release precedence. The following are examples of valid pre-
	release versions		release versions
	1.0.0-alpha.1		1.0.0-alpha.1
	1.0.0-alpha.3		1.0.0-alpha.3
	2.1.0-beta.42		2.1.0-beta.42
	3.0.0-202007.rc.1		3.0.0-202007.rc.1
	When developing a new revision of an existing module using the YANG		When developing a new revision of an existing module or submodule
	semver revision-label scheme, the intended target semver version MUST		using the YANG semver revision-label scheme, the intended target
	be used along with pre-release notation. For example, if a released		semver version MUST be used along with pre-release notation. For
	module which has a current revision-label of 1.0.0 is being modified		example, if a released module or submodule which has a current
	with the intent to make non-backwards-compatible changes, the first		revision-label of 1.0.0 is being modified with the intent to make
	development MAJOR version component must be 2 with some pre-release		non-backwards-compatible changes, the first development MAJOR version
	notation such as -alpha.1, making the version 2.0.0-alpha.1. That		component must be 2 with some pre-release notation such as -alpha.1,
	said, every publicly available release of a module MUST have a unique		making the version 2.0.0-alpha.1. That said, every publicly
	YANG semver revision-label (where a publicly available release is one		available release of a module or submodule MUST have a unique YANG
	that could be implemented by a vendor or consumed by an end user).		semver revision-label (where a publicly available release is one that
			could be implemented by a vendor or consumed by an end user).
	Therefore, it may be prudent to include the year or year and month		Therefore, it may be prudent to include the year or year and month
	development began (e.g., 2.0.0-201907-alpha.1). As a module		development began (e.g., 2.0.0-201907-alpha.1). As a module or
	undergoes development, it is possible that the original intent		submodule undergoes development, it is possible that the original
	changes. For example, a 1.0.0 version of a module that was destined		intent changes. For example, a 1.0.0 version of a module or
	to become 2.0.0 after a development cycle may have had a scope change		submodule that was destined to become 2.0.0 after a development cycle
	such that the final version has no non-backwards-compatible changes		may have had a scope change such that the final version has no non-
	and becomes 1.1.0 instead. This change is acceptable to make during		backwards-compatible changes and becomes 1.1.0 instead. This change
	the development phase so long as pre-release notation is present in		is acceptable to make during the development phase so long as pre-
	both versions (e.g., 2.0.0-alpha.3 becomes 1.1.0-alpha.4). However,		release notation is present in both versions (e.g., 2.0.0-alpha.3
	on the next development cycle (after 1.1.0 is released), if again the		becomes 1.1.0-alpha.4). However, on the next development cycle
	new target release is 2.0.0, new pre-release components must be used		(after 1.1.0 is released), if again the new target release is 2.0.0,
	such that every revision-label for a given module MUST be unique		new pre-release components must be used such that every revision-
	throughout its entire lifecycle (e.g., the first pre-release version		label for a given module or submodule MUST be unique throughout its
	might be 2.0.0-202005-alpha.1 if keeping the same year and month		entire lifecycle (e.g., the first pre-release version might be
	notation mentioned above).		2.0.0-202005-alpha.1 if keeping the same year and month notation
			mentioned above).
	5.1. Pre-release Version Precedence		5.1. Pre-release Version Precedence
	[TODO: Describe precedence considering there could be changes during		As a module or submodule is developed, the scope of the work may
	development and parallel development tracks.]		change. That is, while a ratified module or submodule with revision-
			label 1.0.0 is initially intended to become 2.0.0 in its next
			ratified version, the scope of work may change such that the final
			version is 1.1.0. During the development cycle, the pre-release
			versions could move from 2.0.0-some-pre-release-tag to 1.1.0-some-
			pre-release-tag. This downwards changing of version numbers makes it
			difficult to evaluate semver rules between pre-release versions.
			However, taken independently, each pre-release version can be
			compared to the previously ratified version (e.g., 1.1.0-some-pre-
			release-tag and 2.0.0-some-pre-release-tag can each be compared to
			1.0.0). Module and submodule developers SHOULD maintain only one
			revision statement in a pre-released module or submodule that
			reflects the latest revision. IETF authors MAY choose to include an
			appendix in the associated draft to track overall changes to the
			module or submodule.
	5.2. YANG Semver in IETF Modules		5.2. YANG Semver in IETF Modules
	All publish IETF modules MUST use YANG semantic versions for their		All published IETF modules and submodules MUST use YANG semantic
	revision-labels. For IETF YANG modules that have already been		versions for their revision-labels. For IETF YANG modules and
	published, revision labels MUST be retrospectively applied to all		submodules that have already been published, revision labels MUST be
	existing revisions when the next new revision is created, starting at		retrospectively applied to all existing revisions when the next new
	version "1.0.0" for the initial published revision, and then		revision is created, starting at version "1.0.0" for the initial
	incrementing according to the YANG Semver version rules specified in		published revision, and then incrementing according to the YANG
	Section 3.3 .		Semver version rules specified in Section 3.3 .
	Net new module development within the IETF SHOULD begin with the 0		Net new module or submodule development within the IETF SHOULD begin
	MAJOR number scheme as described above. When revising an existing		with the 0 MAJOR number scheme as described above. When revising an
	IETF module, the revision-label MUST use the target (i.e., intended)		existing IETF module or submodule, the revision-label MUST use the
	MAJOR and MINOR version components with a 0 PATCH version component.		target (i.e., intended) MAJOR and MINOR version components with a 0
	If the intended ratified release will be non-backward-compatible with		PATCH version component. If the intended ratified release will be
	the current ratified release, the MINOR version component MUST be 0.		non-backward-compatible with the current ratified release, the MINOR
			version component MUST be 0.
	All IETF modules in development MUST use the whole document name as a		All IETF modules and submodules in development MUST use the whole
	pre-release version string, including the current document revision.		document name as a pre-release version string, including the current
	For example, if a module which is currently released at version 1.0.0		document revision. For example, if a module or submodule which is
	is being revised to include non-backwards-compatible changes in		currently released at version 1.0.0 is being revised to include non-
	draft-user-netmod-foo, its development revision-labels MUST include		backwards-compatible changes in draft-user-netmod-foo, its
	2.0.0-draft-user-netmod-foo followed by the document's revision		development revision-labels MUST include 2.0.0-draft-user-netmod-foo
	(e.g., 2.0.0-draft-user-netmod-foo-02). This will ensure each pre-		followed by the document's revision (e.g., 2.0.0-draft-user-netmod-
	release version is unique across the lifecycle of the module. Even		foo-02). This will ensure each pre-release version is unique across
	when using the 0 MAJOR version for initial module development (where		the lifecycle of the module or submodule. Even when using the 0
			MAJOR version for initial module or submodule development (where
	MINOR and PATCH can change), appending the draft name as a pre-		MINOR and PATCH can change), appending the draft name as a pre-
	release component helps to ensure uniqueness when there are perhaps		release component helps to ensure uniqueness when there are perhaps
	multiple, parallel efforts creating the same module.		multiple, parallel efforts creating the same module or submodule.
	If a module is being revised and the original module never had a		If a module or submodule is being revised and the original module or
	revision-label (i.e., you wish to start using YANG semver in future		submodule never had a revision-label (i.e., you wish to start using
	module revisions), choose a semver value that makes the most sense		YANG semver in future module or submodule revisions), choose a semver
	based on the module's history. For example, if a module started out		value that makes the most sense based on the module's or submodule's
	in the pre-NMDA ([RFC8342] ) world, and then had NMDA support added		history. For example, if a module or submodule started out in the
	without removing any legacy "state" branches -- and you are looking		pre-NMDA ([RFC8342] ) world, and then had NMDA support added without
	to add additional new features -- a sensible choice for the target		removing any legacy "state" branches -- and you are looking to add
	YANG semver would be 1.2.0 (since 1.0.0 would have been the initial,		additional new features -- a sensible choice for the target YANG
	pre-NMDA release, and 1.1.0 would have been the NMDA revision).		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).
	See Appendix A for a detailed example of IETF pre-release versions.		See Appendix A for a detailed example of IETF pre-release versions.
	6. YANG Module		6. YANG Module
	This YANG module contains the typedef for the YANG semantic version.		This YANG module contains the typedef for the YANG semantic version.
	<CODE BEGINS> file "ietf-yang-semver@2020-06-30.yang"		<CODE BEGINS> file "ietf-yang-semver@2020-06-30.yang"
	module ietf-yang-semver {		module ietf-yang-semver {
	yang-version 1.1;		yang-version 1.1;
	skipping to change at page 17, line 34 ¶		skipping to change at page 19, line 5 ¶
	Module Names" registry:		Module Names" registry:
	Name: ietf-yang-semver		Name: ietf-yang-semver
	XML Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-semver		XML Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-semver
	Prefix: yangver		Prefix: yangver
	Reference: [RFCXXXX]		Reference: [RFCXXXX]
	9.2. Guidance for YANG Semver in IANA maintained YANG modules		9.2. Guidance for YANG Semver in IANA maintained YANG modules and
			submodules
	Note for IANA (to be removed by the RFC editor): Please check that		Note for IANA (to be removed by the RFC editor): Please check that
	the registries and IANA YANG modules are referenced in the		the registries and IANA YANG modules and submodules are referenced in
	appropriate way.		the appropriate way.
	IANA is responsible for maintaining and versioning some YANG modules,		IANA is responsible for maintaining and versioning some YANG modules
	e.g., iana-if-types.yang [IfTypeYang] and iana-routing-types.yang		and submodules, e.g., iana-if-types.yang [IfTypeYang] and iana-
	[RoutingTypesYang] .		routing-types.yang [RoutingTypesYang] .
	In addition to following the rules specified in the IANA		In addition to following the rules specified in the IANA
	Considerations section of [I-D.ietf-netmod-yang-module-versioning] ,		Considerations section of [I-D.ietf-netmod-yang-module-versioning] ,
	IANA maintained YANG modules MUST also include a YANG Semver revision		IANA maintained YANG modules and submodules MUST also include a YANG
	label for all new revisions, as defined in Section 3 .		Semver revision label for all new revisions, as defined in Section 3
			.
	The YANG Semver version associated with the new revision MUST follow		The YANG Semver version associated with the new revision MUST follow
	the rules defined in Section 3.3 .		the rules defined in Section 3.3 .
	Note: For IANA maintained YANG modules that have already been		Note: For IANA maintained YANG modules and submodules that have
	published, revision labels MUST be retrospectively applied to all		already been published, revision labels MUST be retrospectively
	existing revisions when the next new revision is created, starting at		applied to all existing revisions when the next new revision is
	version "1.0.0" for the initial published revision, and then		created, starting at version "1.0.0" for the initial published
	incrementing according to the YANG Semver version rules specified in		revision, and then incrementing according to the YANG Semver version
	Section 3.3 .		rules specified in Section 3.3 .
	Most changes to IANA maintained YANG modules are expected to be		Most changes to IANA maintained YANG modules and submodules are
	backwards-compatible changes and classified as MINOR version changes.		expected to be backwards-compatible changes and classified as MINOR
	The PATCH version may be incremented instead when only editorial		version changes. The PATCH version may be incremented instead when
	changes are made, and the MAJOR version would be incremented if non-		only editorial changes are made, and the MAJOR version would be
	backwards-compatible major changes are made.		incremented if non-backwards-compatible major changes are made.
	Given that IANA maintained YANG modules are versioned with a linear		Given that IANA maintained YANG modules and submodules are versioned
	history, it is anticipated that it should not be necessary to use the		with a linear history, it is anticipated that it should not be
	"_compatible" or "_non_compatible" modifiers to the "Z_COMPAT"		necessary to use the "_compatible" or "_non_compatible" modifiers to
	version element.		the "Z_COMPAT" version element.
	10. References		10. References
	10.1. Normative References		10.1. Normative References
	[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate		[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
	Requirement Levels", BCP 14, RFC 2119,		Requirement Levels", BCP 14, RFC 2119,
	DOI 10.17487/RFC2119, March 1997,		DOI 10.17487/RFC2119, March 1997,
	<https://www.rfc-editor.org/info/rfc2119>.		<https://www.rfc-editor.org/info/rfc2119>.
	skipping to change at page 18, line 45 ¶		skipping to change at page 20, line 18 ¶
	[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., Sterne,		Wilton, R., Rahman, R., Lengyel, B., Clarke, J., Sterne,
	J., Claise, B., and K. D'Souza, "Updated YANG Module		J., Claise, B., and K. D'Souza, "Updated YANG Module
	Revision Handling", Work in Progress, Internet-Draft,		Revision Handling", Work in Progress, Internet-Draft,
	draft-ietf-netmod-yang-module-versioning-01, 10 July 2020,		draft-ietf-netmod-yang-module-versioning-02, 22 February
	<https://tools.ietf.org/html/draft-ietf-netmod-yang-		2021, <https://tools.ietf.org/html/draft-ietf-netmod-yang-
	module-versioning-01>.		module-versioning-02>.
	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>.
	[I-D.ietf-netmod-yang-packages]		[I-D.ietf-netmod-yang-packages]
	Wilton, R., Rahman, R., Clarke, J., Sterne, J., and W. Bo,		Wilton, R., Rahman, R., Clarke, J., Sterne, J., and B. Wu,
	"YANG Packages", Work in Progress, Internet-Draft, draft-		"YANG Packages", Work in Progress, Internet-Draft, draft-
	ietf-netmod-yang-packages-01, 2 November 2020,		ietf-netmod-yang-packages-01, 2 November 2020,
	<https://tools.ietf.org/html/draft-ietf-netmod-yang-		<https://tools.ietf.org/html/draft-ietf-netmod-yang-
	packages-01>.		packages-01>.
			[I-D.ietf-netmod-yang-schema-comparison]
			Wilton, R., "YANG Schema Comparison", Work in Progress,
			Internet-Draft, draft-ietf-netmod-yang-schema-comparison-
			01, 2 November 2020, <https://tools.ietf.org/html/draft-
			ietf-netmod-yang-schema-comparison-01>.
	[RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,		[RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
	and R. Wilton, "Network Management Datastore Architecture		and R. Wilton, "Network Management Datastore Architecture
	(NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018,		(NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018,
	<https://www.rfc-editor.org/info/rfc8342>.		<https://www.rfc-editor.org/info/rfc8342>.
	[openconfigsemver]		[openconfigsemver]
	"Semantic Versioning for Openconfig Models",		"Semantic Versioning for Openconfig Models",
	<http://www.openconfig.net/docs/semver/>.		<http://www.openconfig.net/docs/semver/>.
	[semver] "Semantic Versioning 2.0.0", <https://www.semver.org>.		[semver] "Semantic Versioning 2.0.0 (text from June 19, 2020)",
			<https://github.com/semver/semver/
			blob/8b2e8eec394948632957639dfa99fc7ec6286911/semver.md>.
	[IfTypeYang]		[IfTypeYang]
	"iana-if-type YANG Module",		"iana-if-type YANG Module",
	<https://www.iana.org/assignments/iana-if-type/iana-if-		<https://www.iana.org/assignments/iana-if-type/iana-if-
	type.xhtml>.		type.xhtml>.
	[RoutingTypesYang]		[RoutingTypesYang]
	"iana-routing-types YANG Module",		"iana-routing-types YANG Module",
	<https://www.iana.org/assignments/iana-routing-types/iana-		<https://www.iana.org/assignments/iana-routing-types/iana-
	routing-types.xhtml>.		routing-types.xhtml>.
End of changes. 48 change blocks.
	197 lines changed or deleted		265 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/