Skip to Content
Last modified by Helena on 2025/09/10 11:19
From version 18.1
edited by Artur
on 2025/07/14 10:19
Change comment: Imported from XAR
To version 11.1
edited by Artur
on 2025/05/22 14:46
Change comment: There is no comment for this version

Summary

Details

Page properties
Parent
... ... @@ -1,1 +1,1 @@
1 -Methodology.SDMX 3\.0 Standards\. Section 6\. Technical Notes.WebHome
1 +Methodology.SDMX 3\.0 Standards\. Section 6\. Technical notes.WebHome
Content
... ... @@ -4,33 +4,33 @@
4 4  
5 5  == 14.1 Introduction to Semantic Versioning ==
6 6  
7 -In the world of versioned data modelling exists a dreaded place called "dependency hell." The bigger your data model through organisational, national or international harmonisation grows and the more [[artefacts>>doc:Glossary.Artefact.WebHome]] you integrate into your modelling, the more likely you are to find yourself, one day, in this pit of despair.
7 +In the world of versioned data modelling exists a dreaded place called "dependency hell." The bigger your data model through organisational, national or international harmonisation grows and the more [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]] you integrate into your modelling, the more likely you are to find yourself, one day, in this pit of despair.
8 8  
9 -In systems with many dependencies, releasing new [[artefact>>doc:Glossary.Artefact.WebHome]] [[versions>>doc:Glossary.Version.WebHome]] can quickly become a nightmare. If the dependency specifications are too tight, you are in danger of [[version>>doc:Glossary.Version.WebHome]] lock (the inability to upgrade an [[artefact>>doc:Glossary.Artefact.WebHome]] without having to release new [[versions>>doc:Glossary.Version.WebHome]] of every dependent [[artefact>>doc:Glossary.Artefact.WebHome]]). If dependencies are specified too loosely, you will inevitably be bitten by [[version>>doc:Glossary.Version.WebHome]] promiscuity (assuming compatibility with more future [[versions>>doc:Glossary.Version.WebHome]] than is reasonable). Dependency hell is where you are when [[version>>doc:Glossary.Version.WebHome]] lock and/or [[version>>doc:Glossary.Version.WebHome]] promiscuity prevent you from easily and safely moving your data modelling forward.
9 +In systems with many dependencies, releasing new [[artefact>>doc:xwiki:Glossary.Artefact.WebHome]] (% style="color:#e74c3c" %)versions(%%) can quickly become a nightmare. If the dependency specifications are too tight, you are in danger of (% style="color:#e74c3c" %)version(%%) lock (the inability to upgrade an [[artefact>>doc:xwiki:Glossary.Artefact.WebHome]] without having to release new (% style="color:#e74c3c" %)versions(%%) of every dependent [[artefact>>doc:xwiki:Glossary.Artefact.WebHome]]). If dependencies are specified too loosely, you will inevitably be bitten by (% style="color:#e74c3c" %)version(%%) promiscuity (assuming compatibility with more future (% style="color:#e74c3c" %)versions(%%) than is reasonable). Dependency hell is where you are when (% style="color:#e74c3c" %)version(%%) lock and/or (% style="color:#e74c3c" %)version(%%) promiscuity prevent you from easily and safely moving your data modelling forward.
10 10  
11 -As a very successful solution to the similar problem in software development, "Semantic Versioning" [[__semver.org__>>https://semver.org/]] proposes a simple set of rules and requirements that dictate how [[version>>doc:Glossary.Version.WebHome]] numbers are assigned and incremented. These rules make also perfect sense in the world of versioned data modelling and help to solve the "dependency hell" encountered with previous versions of [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]]. [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] 3.0 applies thus the Semantic Versioning rules on all versioned [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] [[artefacts>>doc:Glossary.Artefact.WebHome]]. Once you release a versioned [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] [[artefact>>doc:Glossary.Artefact.WebHome]], you communicate changes to it with specific increments to your [[version>>doc:Glossary.Version.WebHome]] number.
11 +As a very successful solution to the similar problem in software development, "Semantic Versioning" [[__semver.org__>>https://semver.org/]] proposes a simple set of rules and requirements that dictate how (% style="color:#e74c3c" %)version(%%) numbers are assigned and incremented. These rules make also perfect sense in the world of versioned data modelling and help to solve the "dependency hell" encountered with previous (% style="color:#e74c3c" %)versions(%%) of [[SDMX>>doc:xwiki:Glossary.Statistical data and metadata exchange.WebHome]]. [[SDMX>>doc:xwiki:Glossary.Statistical data and metadata exchange.WebHome]] 3.0 applies thus the Semantic Versioning rules on all versioned [[SDMX>>doc:xwiki:Glossary.Statistical data and metadata exchange.WebHome]] [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]]. Once you release a versioned [[SDMX>>doc:xwiki:Glossary.Statistical data and metadata exchange.WebHome]] [[artefact>>doc:xwiki:Glossary.Artefact.WebHome]], you communicate changes to it with specific increments to your (% style="color:#e74c3c" %)version(%%) number.
12 12  
13 -**This [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] 3.0(.0) specification inherits the original **[[__**semver.org**__>>https://semver.org]]** 2.0.0 wording (license: [[__Creative Commons - CC BY 3.0__>>https://creativecommons.org/licenses/by/3.0/]]) and applies it to versioned [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] structural [[artefacts>>doc:Glossary.Artefact.WebHome]].** Under this scheme, [[version>>doc:Glossary.Version.WebHome]] numbers and the way they change convey meaning about the underlying data structures and what has been modified from one [[version>>doc:Glossary.Version.WebHome]] to the next.
13 +**This [[SDMX>>doc:xwiki:Glossary.Statistical data and metadata exchange.WebHome]] 3.0(.0) specification inherits the original **[[__**semver.org**__>>https://xwiki:semver.org]]** 2.0.0 wording (license: [[__Creative Commons - CC BY 3.0__>>https://creativecommons.org/licenses/by/3.0/]]) and applies it to versioned [[SDMX>>doc:xwiki:Glossary.Statistical data and metadata exchange.WebHome]] structural [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]].** Under this scheme, (% style="color:#e74c3c" %)version(%%) numbers and the way they change convey meaning about the underlying data structures and what has been modified from one (% style="color:#e74c3c" %)version(%%) to the next.
14 14  
15 15  == 14.2 Semantic Versioning Specification for SDMX 3.0(.0) ==
16 16  
17 17  The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
18 18  
19 -In the following, "versioned" [[artefacts>>doc:Glossary.Artefact.WebHome]] are understood to be semantically versioned [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] structural [[artefacts>>doc:Glossary.Artefact.WebHome]], and X, Y, Z and EXT are understood as placeholders for the [[version>>doc:Glossary.Version.WebHome]] parts MAJOR, MINOR, PATCH, and EXTENSION, as defined in chapter 4.3.
19 +In the following, "versioned" [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]] are understood to be semantically versioned [[SDMX>>doc:xwiki:Glossary.Statistical data and metadata exchange.WebHome]] structural [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]], and X, Y, Z and EXT are understood as placeholders for the (% style="color:#e74c3c" %)version(%%) parts MAJOR, MINOR, PATCH, and EXTENSION, as defined in chapter 4.3.
20 20  
21 -The following rules apply to versioned [[artefacts>>doc:Glossary.Artefact.WebHome]]:
21 +The following rules apply to versioned [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]]:
22 22  
23 -* All versioned [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] [[artefacts>>doc:Glossary.Artefact.WebHome]] MUST specify a [[version>>doc:Glossary.Version.WebHome]] number.
24 -* The [[version>>doc:Glossary.Version.WebHome]] number of immutable versioned [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] [[artefacts>>doc:Glossary.Artefact.WebHome]] MUST take the form X.Y.Z where X, Y, and Z are non-negative integers and MUST NOT contain leading zeroes. X is the MAJOR [[version>>doc:Glossary.Version.WebHome]], Y is the MINOR [[version>>doc:Glossary.Version.WebHome]], and Z is the PATCH [[version>>doc:Glossary.Version.WebHome]]. Each element MUST increase numerically. For instance: 1.9.0 -> 1.10.0 -> 1.11.0.
25 -* Once an [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] [[artefact>>doc:Glossary.Artefact.WebHome]] with an X.Y.Z [[version>>doc:Glossary.Version.WebHome]] has been shared externally or publicly released, the contents of that [[version>>doc:Glossary.Version.WebHome]] MUST NOT be modified. That [[artefact>>doc:Glossary.Artefact.WebHome]] [[version>>doc:Glossary.Version.WebHome]] is considered stable. Any modifications MUST be released as a new [[version>>doc:Glossary.Version.WebHome]].
26 -* MAJOR [[version>>doc:Glossary.Version.WebHome]] zero (0.y.z) is for initial modelling. Anything MAY change at any time. The externally released or public [[artefact>>doc:Glossary.Artefact.WebHome]] SHOULD NOT be considered stable.
27 -* [[Version>>doc:Glossary.Version.WebHome]] 1.0.0 defines the first stable [[artefact>>doc:Glossary.Artefact.WebHome]]. The way in which the [[version>>doc:Glossary.Version.WebHome]] number is incremented after this release is dependent on how this externally released or public [[artefact>>doc:Glossary.Artefact.WebHome]] changes.
28 -* PATCH [[version>>doc:Glossary.Version.WebHome]] Z (x.y.Z | x > 0) MUST be incremented if only backwards compatible property changes are introduced. A property change is defined as an internal change that does not affect the relationship to other [[artefacts>>doc:Glossary.Artefact.WebHome]]. These are changes in the [[artefact>>doc:Glossary.Artefact.WebHome]]'s or [[artefact>>doc:Glossary.Artefact.WebHome]] element's names, descriptions and [[annotations>>doc:Glossary.Annotation.WebHome]] that MUST NOT alter their meaning.
29 -* MINOR [[version>>doc:Glossary.Version.WebHome]] Y (x.Y.z | x > 0) MUST be incremented if a new, backwards compatible element is introduced to a stable [[artefact>>doc:Glossary.Artefact.WebHome]]. These are additional items in ItemScheme [[artefacts>>doc:Glossary.Artefact.WebHome]]. It MAY be incremented if substantial new information is introduced within the [[artefact>>doc:Glossary.Artefact.WebHome]]'s properties. It MAY include PATCH level changes. PATCH [[version>>doc:Glossary.Version.WebHome]] MUST be reset to 0 when MINOR [[version>>doc:Glossary.Version.WebHome]] is incremented.
30 -* MAJOR [[version>>doc:Glossary.Version.WebHome]] X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to a stable [[artefact>>doc:Glossary.Artefact.WebHome]]. These often relate to deletions of items in ItemSchemes or to backwards incompatibility introduced due to changes in references to other [[artefacts>>doc:Glossary.Artefact.WebHome]]. A MAJOR [[version>>doc:Glossary.Version.WebHome]] change MAY also include MINOR and PATCH level changes. PATCH and MINOR [[version>>doc:Glossary.Version.WebHome]] MUST be reset to 0 when MAJOR [[version>>doc:Glossary.Version.WebHome]] is incremented.
31 -* A mutable [[version>>doc:Glossary.Version.WebHome]], e.g. used for externally released or public drafts or as prerelease, MUST be denoted by appending an EXTENSION that consists of a hyphen and a series of dot separated identifiers immediately following the PATCH [[version>>doc:Glossary.Version.WebHome]] (x.y.z-EXT). Identifiers MUST comprise only ASCII alphanumerics and hyphen [0-9A-Za-z-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. However, to foster harmonisation and general comprehension it is generally recommended to use the standard EXTENSION "**-draft**". Extended [[versions>>doc:Glossary.Version.WebHome]] have a lower precedence than the associated stable [[version>>doc:Glossary.Version.WebHome]]. An extended [[version>>doc:Glossary.Version.WebHome]] indicates that the [[version>>doc:Glossary.Version.WebHome]] is unstable and it might not satisfy the intended compatibility requirements as denoted by its associated stable [[version>>doc:Glossary.Version.WebHome]]. When making changes to an [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] [[artefact>>doc:Glossary.Artefact.WebHome]] with an extended [[version>>doc:Glossary.Version.WebHome]] number then one is not required to increment the [[version>>doc:Glossary.Version.WebHome]] if those changes are kept within the allowed scope of the [[version>>doc:Glossary.Version.WebHome]] increment from the previous [[version>>doc:Glossary.Version.WebHome]] (if that existed), otherwise also here the before mentioned [[version>>doc:Glossary.Version.WebHome]] increment rules for X.Y.Z apply. Concretely, a [[version>>doc:Glossary.Version.WebHome]] X.0.0-EXT will allow for any changes, a [[version>>doc:Glossary.Version.WebHome]] X.Y.0-EXT will allow only for MINOR changes and a [[version>>doc:Glossary.Version.WebHome]] X.Y.Z-EXT will allow only for any PATCH changes, as defined above. EXTENSION examples: 1.0.0-draft, 1.0.0-draft.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92.
32 -* Precedence refers to how [[versions>>doc:Glossary.Version.WebHome]] are compared to each other when ordered. Precedence MUST be calculated by separating the [[version>>doc:Glossary.Version.WebHome]] into MAJOR, MINOR, PATCH and EXTENSION identifiers in that order. Precedence is determined by the first difference when comparing each of these identifiers from left to right as follows: MAJOR, MINOR, and PATCH [[versions>>doc:Glossary.Version.WebHome]] are always compared numerically. Example: 1.0.0 < 2.0.0 < 2.1.0 < 2.1.1. When MAJOR, MINOR, and PATCH are equal, an extended [[version>>doc:Glossary.Version.WebHome]] has lower precedence than a stable [[version>>doc:Glossary.Version.WebHome]]. Example: 1.0.0-draft < 1.0.0. Precedence for two extended [[versions>>doc:Glossary.Version.WebHome]] with the same MAJOR, MINOR, and PATCH [[version>>doc:Glossary.Version.WebHome]] MUST be determined by comparing each dot separated identifier from left to right until a difference is found as follows: identifiers consisting of only digits are compared numerically and identifiers with letters or hyphens are compared lexically in ASCII sort order. Numeric identifiers always have lower precedence than non-numeric identifiers. A larger set of EXTENSION fields has a higher precedence than a smaller set, if all of the preceding identifiers are equal. Example: 1.0.0-draft < 1.0.0-draft.1 < 1.0.0-draft.prerelease < 1.0.0-prerelease < 1.0.0-prerelease.2 < 1.0.0-prerelease.11 < 1.0.0-rc.1 < 1.0.0.
33 -* The reasons for [[version>>doc:Glossary.Version.WebHome]] changes MAY be documented in brief form in an [[artefact>>doc:Glossary.Artefact.WebHome]]'s [[annotation>>doc:Glossary.Annotation.WebHome]] of type "CHANGELOG".
23 +* All versioned [[SDMX>>doc:xwiki:Glossary.Statistical data and metadata exchange.WebHome]] [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]] MUST specify a (% style="color:#e74c3c" %)version(%%) number.
24 +* The (% style="color:#e74c3c" %)version(%%) number of immutable versioned [[SDMX>>doc:xwiki:Glossary.Statistical data and metadata exchange.WebHome]] [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]] MUST take the form X.Y.Z where X, Y, and Z are non-negative integers and MUST NOT contain leading zeroes. X is the MAJOR (% style="color:#e74c3c" %)version(%%), Y is the MINOR (% style="color:#e74c3c" %)version(%%), and Z is the PATCH (% style="color:#e74c3c" %)version(%%). Each element MUST increase numerically. For instance: 1.9.0 -> 1.10.0 -> 1.11.0.
25 +* Once an [[SDMX>>doc:xwiki:Glossary.Statistical data and metadata exchange.WebHome]] [[artefact>>doc:xwiki:Glossary.Artefact.WebHome]] with an X.Y.Z (% style="color:#e74c3c" %)version(%%) has been shared externally or publicly released, the contents of that (% style="color:#e74c3c" %)version(%%) MUST NOT be modified. That [[artefact>>doc:xwiki:Glossary.Artefact.WebHome]] (% style="color:#e74c3c" %)version(%%) is considered stable. Any modifications MUST be released as a new (% style="color:#e74c3c" %)version(%%).
26 +* MAJOR (% style="color:#e74c3c" %)version(%%) zero (0.y.z) is for initial modelling. Anything MAY change at any time. The externally released or public [[artefact>>doc:xwiki:Glossary.Artefact.WebHome]] SHOULD NOT be considered stable.
27 +* (% style="color:#e74c3c" %)Version(%%) 1.0.0 defines the first stable [[artefact>>doc:xwiki:Glossary.Artefact.WebHome]]. The way in which the (% style="color:#e74c3c" %)version(%%) number is incremented after this release is dependent on how this externally released or public [[artefact>>doc:xwiki:Glossary.Artefact.WebHome]] changes.
28 +* PATCH (% style="color:#e74c3c" %)version(%%) Z (x.y.Z | x > 0) MUST be incremented if only backwards compatible property changes are introduced. A property change is defined as an internal change that does not affect the relationship to other [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]]. These are changes in the [[artefact>>doc:xwiki:Glossary.Artefact.WebHome]]'s or [[artefact>>doc:xwiki:Glossary.Artefact.WebHome]] element's names, descriptions and [[annotations>>doc:xwiki:Glossary.Annotation.WebHome]] that MUST NOT alter their meaning.
29 +* MINOR (% style="color:#e74c3c" %)version(%%) Y (x.Y.z | x > 0) MUST be incremented if a new, backwards compatible element is introduced to a stable [[artefact>>doc:xwiki:Glossary.Artefact.WebHome]]. These are additional items in ItemScheme [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]]. It MAY be incremented if substantial new information is introduced within the [[artefact>>doc:xwiki:Glossary.Artefact.WebHome]]'s properties. It MAY include PATCH (% style="color:#e74c3c" %)level(%%) changes. PATCH (% style="color:#e74c3c" %)version(%%) MUST be reset to 0 when MINOR (% style="color:#e74c3c" %)version(%%) is incremented.
30 +* MAJOR (% style="color:#e74c3c" %)version(%%) X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to a stable [[artefact>>doc:xwiki:Glossary.Artefact.WebHome]]. These often relate to deletions of items in ItemSchemes or to backwards incompatibility introduced due to changes in references to other [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]]. A MAJOR (% style="color:#e74c3c" %)version(%%) change MAY also include MINOR and PATCH (% style="color:#e74c3c" %)level(%%) changes. PATCH and MINOR (% style="color:#e74c3c" %)version(%%) MUST be reset to 0 when MAJOR (% style="color:#e74c3c" %)version(%%) is incremented.
31 +* A mutable (% style="color:#e74c3c" %)version(%%), e.g. used for externally released or public drafts or as prerelease, MUST be denoted by appending an EXTENSION that consists of a hyphen and a series of dot separated identifiers immediately following the PATCH (% style="color:#e74c3c" %)version(%%) (x.y.z-EXT). Identifiers MUST comprise only ASCII alphanumerics and hyphen [0-9A-Za-z-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. However, to foster harmonisation and general comprehension it is generally recommended to use the standard EXTENSION "**-draft**". Extended (% style="color:#e74c3c" %)versions(%%) have a lower precedence than the associated stable (% style="color:#e74c3c" %)version(%%). An extended (% style="color:#e74c3c" %)version(%%) indicates that the (% style="color:#e74c3c" %)version(%%) is unstable and it might not satisfy the intended compatibility requirements as denoted by its associated stable (% style="color:#e74c3c" %)version(%%). When making changes to an [[SDMX>>doc:xwiki:Glossary.Statistical data and metadata exchange.WebHome]] [[artefact>>doc:xwiki:Glossary.Artefact.WebHome]] with an extended (% style="color:#e74c3c" %)version(%%) number then one is not required to increment the (% style="color:#e74c3c" %)version(%%) if those changes are kept within the allowed scope of the (% style="color:#e74c3c" %)version(%%) increment from the previous (% style="color:#e74c3c" %)version(%%) (if that existed), otherwise also here the before mentioned (% style="color:#e74c3c" %)version(%%) increment rules for X.Y.Z apply. Concretely, a (% style="color:#e74c3c" %)version(%%) X.0.0-EXT will allow for any changes, a (% style="color:#e74c3c" %)version(%%) X.Y.0-EXT will allow only for MINOR changes and a (% style="color:#e74c3c" %)version(%%) X.Y.Z-EXT will allow only for any PATCH changes, as defined above. EXTENSION examples: 1.0.0-draft, 1.0.0-draft.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92.
32 +* Precedence refers to how (% style="color:#e74c3c" %)versions(%%) are compared to each other when ordered. Precedence MUST be calculated by separating the (% style="color:#e74c3c" %)version(%%) into MAJOR, MINOR, PATCH and EXTENSION identifiers in that order. Precedence is determined by the first difference when comparing each of these identifiers from left to right as follows: MAJOR, MINOR, and PATCH (% style="color:#e74c3c" %)versions(%%) are always compared numerically. Example: 1.0.0 < 2.0.0 < 2.1.0 < 2.1.1. When MAJOR, MINOR, and PATCH are equal, an extended (% style="color:#e74c3c" %)version(%%) has lower precedence than a stable (% style="color:#e74c3c" %)version(%%). Example: 1.0.0-draft < 1.0.0. Precedence for two extended (% style="color:#e74c3c" %)versions(%%) with the same MAJOR, MINOR, and PATCH (% style="color:#e74c3c" %)version(%%) MUST be determined by comparing each dot separated identifier from left to right until a difference is found as follows: identifiers consisting of only digits are compared numerically and identifiers with letters or hyphens are compared lexically in ASCII sort order. Numeric identifiers always have lower precedence than non-numeric identifiers. A larger set of EXTENSION fields has a higher precedence than a smaller set, if all of the preceding identifiers are equal. Example: 1.0.0-draft < 1.0.0-draft.1 < 1.0.0-draft.prerelease < 1.0.0-prerelease < 1.0.0-prerelease.2 < 1.0.0-prerelease.11 < 1.0.0-rc.1 < 1.0.0.
33 +* The reasons for (% style="color:#e74c3c" %)version(%%) changes MAY be documented in brief form in an [[artefact>>doc:xwiki:Glossary.Artefact.WebHome]]'s [[annotation>>doc:xwiki:Glossary.Annotation.WebHome]] of type "CHANGELOG".
34 34  
35 35  == 14.3 Backus–Naur Form Grammar for Valid SDMX 3.0(.0) Semantic Versions ==
36 36  
... ... @@ -39,103 +39,103 @@
39 39  
40 40  == 14.4 Dependency Management in SDMX 3.0(.0): ==
41 41  
42 -MAJOR, MINOR or PATCH [[version>>doc:Glossary.Version.WebHome]] parts in [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] 3.0 [[artefact>>doc:Glossary.Artefact.WebHome]] references CAN be wildcarded using "+" as extension:
42 +MAJOR, MINOR or PATCH (% style="color:#e74c3c" %)version(%%) parts in [[SDMX>>doc:xwiki:Glossary.Statistical data and metadata exchange.WebHome]] 3.0 [[artefact>>doc:xwiki:Glossary.Artefact.WebHome]] references CAN be wildcarded using "+" as extension:
43 43  
44 -* X+.Y.Z means the currently latest available [[version>>doc:Glossary.Version.WebHome]] >= X.Y.Z
45 -** Example: "2+.3.1" means the currently latest available [[version>>doc:Glossary.Version.WebHome]] >="2.3.1" (even if not backwards compatible)
46 -** Typical use case: references in [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] Categorisations
47 -* X.Y+.Z means the currently latest available backwards compatible [[version>>doc:Glossary.Version.WebHome]] >=X.Y.Z
48 -** Example: "2.3+.1" means the currently latest available [[version>>doc:Glossary.Version.WebHome]] >= "2.3.1" and < "3.0.0" (all backwards compatible [[versions>>doc:Glossary.Version.WebHome]] >="2.3.1")
49 -** Typical use case: references in [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] DSD
50 -* X.Y.Z+ means the currently latest available forwards and backwards compatible [[version>>doc:Glossary.Version.WebHome]] >= X.Y.Z
51 -** Example: "2.3.1+" means the currently latest available [[version>>doc:Glossary.Version.WebHome]] >= "2.3.1" and < "2.4.0" (all forwards and backwards compatible [[versions>>doc:Glossary.Version.WebHome]] >= "2.3.1")
52 -* Non-versioned and 2-digit [[version>>doc:Glossary.Version.WebHome]] [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] structural [[artefacts>>doc:Glossary.Artefact.WebHome]] CAN reference any other non-versioned or versioned (whether SemVer or not) [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] structural [[artefacts>>doc:Glossary.Artefact.WebHome]].
53 -* Semantically versioned [[artefacts>>doc:Glossary.Artefact.WebHome]] MUST only reference other semantically versioned [[artefacts>>doc:Glossary.Artefact.WebHome]].
54 -* Wildcarded references in a stable [[artefact>>doc:Glossary.Artefact.WebHome]] implicitly target only future stable [[versions>>doc:Glossary.Version.WebHome]] of the referenced [[artefacts>>doc:Glossary.Artefact.WebHome]] within the defined wildcard scope.
55 -** Example: The reference to "AGENCY_ID:CODELIST_ID(2.3+.1)" in an [[artefact>>doc:Glossary.Artefact.WebHome]] "AGENCY_ID:DSD_ID(2.2.1)" resolves to [[artefact>>doc:Glossary.Artefact.WebHome]] "AGENCY_ID:CODELIST_ID(2.4.3)" if that was currently the latest available stable [[version>>doc:Glossary.Version.WebHome]].
56 -* Wildcarded references in a version-extended [[artefact>>doc:Glossary.Artefact.WebHome]] implicitly target future stable and version-extended [[versions>>doc:Glossary.Version.WebHome]] of the referenced [[artefacts>>doc:Glossary.Artefact.WebHome]] within the defined wildcard scope.
57 -** Example: The reference to "AGENCY_ID:CODELIST_ID(2.3+.1)" in an [[artefact>>doc:Glossary.Artefact.WebHome]] "AGENCY_ID:DSD_ID(2.2.1-draft)" resolves to [[artefact>>doc:Glossary.Artefact.WebHome]] "AGENCY_ID:CODELIST_ID(2.5.0-draft)" if that was currently the latest available [[version>>doc:Glossary.Version.WebHome]].
58 -* References to specific version-extended [[artefacts>>doc:Glossary.Artefact.WebHome]] MAY be used, but those cannot be combined with a wildcard.
59 -** Example: The reference to "AGENCY_ID:CODELIST_ID(2.5.0draft)" in an [[artefact>>doc:Glossary.Artefact.WebHome]] "AGENCY_ID:DSD_ID(2.2.1)" resolves to [[artefact>>doc:Glossary.Artefact.WebHome]] "AGENCY_ID:CODELIST_ID(2.5.0-draft)", which might be subject to continued backwards compatible changes.
44 +* X+.Y.Z means the currently latest available (% style="color:#e74c3c" %)version(%%) >= X.Y.Z
45 +** Example: "2+.3.1" means the currently latest available (% style="color:#e74c3c" %)version(%%) >="2.3.1" (even if not backwards compatible)
46 +** Typical use case: references in [[SDMX>>doc:xwiki:Glossary.Statistical data and metadata exchange.WebHome]] Categorisations
47 +* X.Y+.Z means the currently latest available backwards compatible (% style="color:#e74c3c" %)version(%%) >=X.Y.Z
48 +** Example: "2.3+.1" means the currently latest available (% style="color:#e74c3c" %)version(%%) >= "2.3.1" and < "3.0.0" (all backwards compatible (% style="color:#e74c3c" %)versions(%%) >="2.3.1")
49 +** Typical use case: references in [[SDMX>>doc:xwiki:Glossary.Statistical data and metadata exchange.WebHome]] DSD
50 +* X.Y.Z+ means the currently latest available forwards and backwards compatible (% style="color:#e74c3c" %)version(%%) >= X.Y.Z
51 +** Example: "2.3.1+" means the currently latest available (% style="color:#e74c3c" %)version(%%) >= "2.3.1" and < "2.4.0" (all forwards and backwards compatible (% style="color:#e74c3c" %)versions(%%) >= "2.3.1")
52 +* Non-versioned and 2-digit (% style="color:#e74c3c" %)version(%%) [[SDMX>>doc:xwiki:Glossary.Statistical data and metadata exchange.WebHome]] structural [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]] CAN reference any other non-versioned or versioned (whether SemVer or not) [[SDMX>>doc:xwiki:Glossary.Statistical data and metadata exchange.WebHome]] structural [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]].
53 +* Semantically versioned [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]] MUST only reference other semantically versioned [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]].
54 +* Wildcarded references in a stable [[artefact>>doc:xwiki:Glossary.Artefact.WebHome]] implicitly target only future stable (% style="color:#e74c3c" %)versions(%%) of the referenced [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]] within the defined wildcard scope.
55 +** Example: The reference to "AGENCY_ID:CODELIST_ID(2.3+.1)" in an [[artefact>>doc:xwiki:Glossary.Artefact.WebHome]] "AGENCY_ID:DSD_ID(2.2.1)" resolves to [[artefact>>doc:xwiki:Glossary.Artefact.WebHome]] "AGENCY_ID:CODELIST_ID(2.4.3)" if that was currently the latest available stable (% style="color:#e74c3c" %)version(%%).
56 +* Wildcarded references in a (% style="color:#e74c3c" %)version(%%)-extended [[artefact>>doc:xwiki:Glossary.Artefact.WebHome]] implicitly target future stable and (% style="color:#e74c3c" %)version(%%)-extended (% style="color:#e74c3c" %)versions(%%) of the referenced [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]] within the defined wildcard scope.
57 +** Example: The reference to "AGENCY_ID:CODELIST_ID(2.3+.1)" in an [[artefact>>doc:xwiki:Glossary.Artefact.WebHome]] "AGENCY_ID:DSD_ID(2.2.1-draft)" resolves to [[artefact>>doc:xwiki:Glossary.Artefact.WebHome]] "AGENCY_ID:CODELIST_ID(2.5.0-draft)" if that was currently the latest available (% style="color:#e74c3c" %)version(%%).
58 +* References to specific (% style="color:#e74c3c" %)version(%%)-extended [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]] MAY be used, but those cannot be combined with a wildcard.
59 +** Example: The reference to "AGENCY_ID:CODELIST_ID(2.5.0draft)" in an [[artefact>>doc:xwiki:Glossary.Artefact.WebHome]] "AGENCY_ID:DSD_ID(2.2.1)" resolves to [[artefact>>doc:xwiki:Glossary.Artefact.WebHome]] "AGENCY_ID:CODELIST_ID(2.5.0-draft)", which might be subject to continued backwards compatible changes.
60 60  
61 -Because both, wildcarded references and references to version-extended [[artefacts>>doc:Glossary.Artefact.WebHome]], allow for changes in the referenced [[artefacts>>doc:Glossary.Artefact.WebHome]], care needs to be taken when choosing the appropriate references in order to achieve the required limitation in the allowed scope of changes.
61 +Because both, wildcarded references and references to (% style="color:#e74c3c" %)version(%%)-extended [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]], allow for changes in the referenced [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]], care needs to be taken when choosing the appropriate references in order to achieve the required limitation in the allowed scope of changes.
62 62  
63 -For references to non-dependent [[artefacts>>doc:Glossary.Artefact.WebHome]], MAJOR, MINOR or PATCH [[version>>doc:Glossary.Version.WebHome]] parts in [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] 3.0 [[artefact>>doc:Glossary.Artefact.WebHome]] references CAN alternatively be wildcarded using "*" as replacement:
63 +For references to non-dependent [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]], MAJOR, MINOR or PATCH (% style="color:#e74c3c" %)version(%%) parts in [[SDMX>>doc:xwiki:Glossary.Statistical data and metadata exchange.WebHome]] 3.0 [[artefact>>doc:xwiki:Glossary.Artefact.WebHome]] references CAN alternatively be wildcarded using "*" as replacement:
64 64  
65 -~* means all available [[versions>>doc:Glossary.Version.WebHome]]
65 +~* means all available (% style="color:#e74c3c" %)versions
66 66  
67 67  == 14.5 Upgrade and conversions of artefacts defined with previous SDMX standard versions to Semantic Versioning ==
68 68  
69 -Because [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] standardises the interactions between statistical systems, which cannot all be upgraded at the same time, the new versioning rules cannot be applied to existing [[artefacts>>doc:Glossary.Artefact.WebHome]] in EDIFACT, [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] 1.0, 2.0 or 2.1. SemVer can only be applied to structural [[artefacts>>doc:Glossary.Artefact.WebHome]] that are newly modelled with the [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] 3.0 Information Model. Migrating to SemVer means migrating to the [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] 3.0 Information Model, to its new API [[version>>doc:Glossary.Version.WebHome]] and new [[versions>>doc:Glossary.Version.WebHome]] of its exchange message formats.
69 +Because [[SDMX>>doc:xwiki:Glossary.Statistical data and metadata exchange.WebHome]] standardises the interactions between statistical systems, which cannot all be upgraded at the same time, the new versioning rules cannot be applied to existing [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]] in EDIFACT, [[SDMX>>doc:xwiki:Glossary.Statistical data and metadata exchange.WebHome]] 1.0, 2.0 or 2.1. SemVer can only be applied to structural [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]] that are newly modelled with the [[SDMX>>doc:xwiki:Glossary.Statistical data and metadata exchange.WebHome]] 3.0 Information Model. Migrating to SemVer means migrating to the [[SDMX>>doc:xwiki:Glossary.Statistical data and metadata exchange.WebHome]] 3.0 Information Model, to its new API (% style="color:#e74c3c" %)version(%%) and new (% style="color:#e74c3c" %)versions(%%) of its exchange message formats.
70 70  
71 -To migrate [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] structural [[artefacts>>doc:Glossary.Artefact.WebHome]] created previously to [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] 3.0.0:
71 +To migrate [[SDMX>>doc:xwiki:Glossary.Statistical data and metadata exchange.WebHome]] structural [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]] created previously to [[SDMX>>doc:xwiki:Glossary.Statistical data and metadata exchange.WebHome]] 3.0.0:
72 72  
73 -If the [[artefacts>>doc:Glossary.Artefact.WebHome]] do not need versioning, then the new [[artefacts>>doc:Glossary.Artefact.WebHome]] based on the [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] 3.0 Information Model SHOULD remain as-is, e.g., a previous [[artefact>>doc:Glossary.Artefact.WebHome]] with the non-final [[version>>doc:Glossary.Version.WebHome]] 1.0 and that doesn't need versioning becomes non-versioned, i.e., keeps [[version>>doc:Glossary.Version.WebHome]] 1.0. This will be the case for all AgencyScheme [[artefacts>>doc:Glossary.Artefact.WebHome]].
73 +If the [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]] do not need versioning, then the new [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]] based on the [[SDMX>>doc:xwiki:Glossary.Statistical data and metadata exchange.WebHome]] 3.0 Information Model SHOULD remain as-is, e.g., a previous [[artefact>>doc:xwiki:Glossary.Artefact.WebHome]] with the non-final (% style="color:#e74c3c" %)version(%%) 1.0 and that doesn't need versioning becomes non-versioned, i.e., keeps (% style="color:#e74c3c" %)version(%%) 1.0. This will be the case for all AgencyScheme [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]].
74 74  
75 -If [[artefact>>doc:Glossary.Artefact.WebHome]] versioning is required and [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] 3.0.0 Semantic Versioning is available within the tools and processes used, then it is recommended to switch to Semantic Versioning with the following steps:
75 +If [[artefact>>doc:xwiki:Glossary.Artefact.WebHome]] versioning is required and [[SDMX>>doc:xwiki:Glossary.Statistical data and metadata exchange.WebHome]] 3.0.0 Semantic Versioning is available within the tools and processes used, then it is recommended to switch to Semantic Versioning with the following steps:
76 76  
77 -1. Complement the missing [[version>>doc:Glossary.Version.WebHome]] parts with 0s to make the [[version>>doc:Glossary.Version.WebHome]] number SemVer-compliant using the MAJOR.MINOR.PATCH-EXTENSION syntax:
77 +1. Complement the missing (% style="color:#e74c3c" %)version(%%) parts with 0s to make the (% style="color:#e74c3c" %)version(%%) number SemVer-compliant using the MAJOR.MINOR.PATCH-EXTENSION syntax:
78 78  
79 - Example: Version 2 becomes version 2.0.0 and version 3.1 becomes version 3.1.0.
79 + Example: (% style="color:#e74c3c" %)Version(%%) 2 becomes (% style="color:#e74c3c" %)version(%%) 2.0.0 and (% style="color:#e74c3c" %)version(%%) 3.1 becomes (% style="color:#e74c3c" %)version(%%) 3.1.0.
80 80  
81 -1. Replace the "isFinal=false" property by the version extensions "-draft" (or alternatively "-unstable" or "-nonfinal" depending on the use case).
81 +1. Replace the "isFinal=false" property by the (% style="color:#e74c3c" %)version(%%) extensions "-draft" (or alternatively "-unstable" or "-nonfinal" depending on the use case).
82 82  
83 - Example: Version 1.3 with isFinal=true becomes version 1.3.0 and version 1.3 with isFinal=false becomes version 1.3.0-draft.
83 + Example: (% style="color:#e74c3c" %)Version(%%) 1.3 with isFinal=true becomes (% style="color:#e74c3c" %)version(%%) 1.3.0 and (% style="color:#e74c3c" %)version(%%) 1.3 with isFinal=false becomes (% style="color:#e74c3c" %)version(%%) 1.3.0-draft.
84 84  
85 -If [[artefact>>doc:Glossary.Artefact.WebHome]] versioning is required but semantic versioning cannot be applied, then version strings used in previous versions of the Standard (e.g., version=1.2) may continue to be used.
85 +If [[artefact>>doc:xwiki:Glossary.Artefact.WebHome]] versioning is required but semantic versioning cannot be applied, then (% style="color:#e74c3c" %)version(%%) strings used in previous (% style="color:#e74c3c" %)versions(%%) of the Standard (e.g., (% style="color:#e74c3c" %)version(%%)=1.2) may continue to be used.
86 86  
87 -Note: Like for other not fully backwards compatible [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] 3.0 features, also some cases of semantically versioned [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] 3.0 [[artefacts>>doc:Glossary.Artefact.WebHome]] cannot be converted back to earlier [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] versions. This is the case when one or more extensions have been created in parallel to the corresponding stable version. In this case, only the stable [[version>>doc:Glossary.Version.WebHome]] SHOULD be converted to a final version (e.g., 3.2.1 becomes 3.2.1 final, and 3.2.1-draft cannot be converted back).
87 +Note: Like for other not fully backwards compatible [[SDMX>>doc:xwiki:Glossary.Statistical data and metadata exchange.WebHome]] 3.0 features, also some cases of semantically versioned [[SDMX>>doc:xwiki:Glossary.Statistical data and metadata exchange.WebHome]] 3.0 [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]] cannot be converted back to earlier [[SDMX>>doc:xwiki:Glossary.Statistical data and metadata exchange.WebHome]] (% style="color:#e74c3c" %)versions(%%). This is the case when one or more extensions have been created in parallel to the corresponding stable (% style="color:#e74c3c" %)version(%%). In this case, only the stable (% style="color:#e74c3c" %)version(%%) SHOULD be converted to a final (% style="color:#e74c3c" %)version(%%) (e.g., 3.2.1 becomes 3.2.1 final, and 3.2.1-draft cannot be converted back).
88 88  
89 89  == 14.6 FAQ for Semantic Versioning ==
90 90  
91 91  **My organisation is new to SDMX and starts to implement 3.0 or starts to implement a new process fully based on SDMX 3.0. Which versioning scheme should be used?**
92 92  
93 -If all counterparts involved in the process and all tools used for its implementation are [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] 3.0-ready, then it is recommended to:
93 +If all counterparts involved in the process and all tools used for its implementation are [[SDMX>>doc:xwiki:Glossary.Statistical data and metadata exchange.WebHome]] 3.0-ready, then it is recommended to:
94 94  
95 95  * in general, use semantic versioning;
96 -* exceptionally, do not use versioning for [[artefacts>>doc:Glossary.Artefact.WebHome]] that do not require it, e.g. [[artefacts>>doc:Glossary.Artefact.WebHome]] that never change, that are only used internally or for which communication on changes with external parties or systems is not required.
96 +* exceptionally, do not use versioning for [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]] that do not require it, e.g. [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]] that never change, that are only used internally or for which communication on changes with external parties or systems is not required.
97 97  
98 98  **How should I deal with revisions in the 0.y.z initial modelling phase?**
99 99  
100 -The simplest thing to do is start your initial modelling release at 0.1.0 and then increment the minor [[version>>doc:Glossary.Version.WebHome]] for each subsequent release.
100 +The simplest thing to do is start your initial modelling release at 0.1.0 and then increment the minor (% style="color:#e74c3c" %)version(%%) for each subsequent release.
101 101  
102 102  **How do I know when to release 1.0.0?**
103 103  
104 -If your data model is being used in production, it should probably already be 1.0.0. If you have a stable [[artefact>>doc:Glossary.Artefact.WebHome]] on which users have come to depend, you should be 1.0.0. If you're worrying a lot about backwards compatibility, you should probably already be 1.0.0.
104 +If your data model is being used in production, it should probably already be 1.0.0. If you have a stable [[artefact>>doc:xwiki:Glossary.Artefact.WebHome]] on which users have come to depend, you should be 1.0.0. If you're worrying a lot about backwards compatibility, you should probably already be 1.0.0.
105 105  
106 106  **Doesn't this discourage rapid modelling and fast iteration?**
107 107  
108 -Major [[version>>doc:Glossary.Version.WebHome]] zero is all about rapid modelling. If you're changing the [[artefact>>doc:Glossary.Artefact.WebHome]] every day you should either still be in [[version>>doc:Glossary.Version.WebHome]] 0.y.z or on the next (minor or) major [[version>>doc:Glossary.Version.WebHome]] for a separate modelling.
108 +Major (% style="color:#e74c3c" %)version(%%) zero is all about rapid modelling. If you're changing the [[artefact>>doc:xwiki:Glossary.Artefact.WebHome]] every day you should either still be in (% style="color:#e74c3c" %)version(%%) 0.y.z or on the next (minor or) major (% style="color:#e74c3c" %)version(%%) for a separate modelling.
109 109  
110 -**If even the tiniest backwards incompatible changes to the public artefact require a major version bump, won't I end up at version 42.0.0 very rapidly?**
110 +**If even the tiniest backwards incompatible changes to the public artefact require a major (% style="color:#e74c3c" %)version(%%) bump, won't I end up at (% style="color:#e74c3c" %)version(%%) 42.0.0 very rapidly?**
111 111  
112 -This is a question of responsible modelling and foresight. Incompatible changes should not be introduced lightly to a data model that has a lot of dependencies. The cost that must be incurred to upgrade can be significant. Having to bump major [[versions>>doc:Glossary.Version.WebHome]] to release incompatible changes means you will think through the impact of your changes, and evaluate the cost/benefit ratio involved.
112 +This is a question of responsible modelling and foresight. Incompatible changes should not be introduced lightly to a data model that has a lot of dependencies. The cost that must be incurred to upgrade can be significant. Having to bump major (% style="color:#e74c3c" %)versions(%%) to release incompatible changes means you will think through the impact of your changes, and evaluate the cost/benefit ratio involved.
113 113  
114 -**Documenting the version changes in an artefact's annotation of type "CHANGELOG" is too much work!**
114 +**Documenting the (% style="color:#e74c3c" %)version(%%) changes in an artefact's annotation of type "CHANGELOG" is too much work!**
115 115  
116 -It is your responsibility as a professional modeller to properly document the [[artefacts>>doc:Glossary.Artefact.WebHome]] that are intended for use by others. Managing data model complexity is a hugely important part of keeping a project efficient, and that's hard to do if nobody knows how to use your data model, or what [[artefacts>>doc:Glossary.Artefact.WebHome]] are safe to reuse. In the long run, [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] 3.0 Semantic Versioning can keep everyone and everything running smoothly.
116 +It is your responsibility as a professional modeller to properly document the [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]] that are intended for use by others. Managing data model complexity is a hugely important part of keeping a project efficient, and that's hard to do if nobody knows how to use your data model, or what [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]] are safe to reuse. In the long run, [[SDMX>>doc:xwiki:Glossary.Statistical data and metadata exchange.WebHome]] 3.0 Semantic Versioning can keep everyone and everything running smoothly.
117 117  
118 -However, refrain from overdoing. Nobody can and will read too long lists of changes. Thus, keep it to the absolute essence, and mainly use it for short announcements. You can even skip the changelog if the change is impact-less. For all complete reports, a new API feature could be more useful to automatically generate a log of differences between two [[versions>>doc:Glossary.Version.WebHome]].
118 +However, refrain from overdoing. Nobody can and will read too long lists of changes. Thus, keep it to the absolute essence, and mainly use it for short announcements. You can even skip the changelog if the change is impact-less. For all complete reports, a new API feature could be more useful to automatically generate a log of differences between two (% style="color:#e74c3c" %)versions(%%).
119 119  
120 -**What do I do if I accidentally release a backwards incompatible change as a minor version?**
120 +**What do I do if I accidentally release a backwards incompatible change as a minor (% style="color:#e74c3c" %)version(%%)?**
121 121  
122 -As soon as you realise that you've broken the [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] 3.0 Semantic Versioning specification, fix the problem and release a new minor [[version>>doc:Glossary.Version.WebHome]] that corrects the problem and restores backwards compatibility. Even under this circumstance, it is unacceptable to modify versioned releases. If it's appropriate, document the offending [[version>>doc:Glossary.Version.WebHome]] and inform your users of the problem so that they are aware of the offending [[version>>doc:Glossary.Version.WebHome]].
122 +As soon as you realise that you've broken the [[SDMX>>doc:xwiki:Glossary.Statistical data and metadata exchange.WebHome]] 3.0 Semantic Versioning specification, fix the problem and release a new minor (% style="color:#e74c3c" %)version(%%) that corrects the problem and restores backwards compatibility. Even under this circumstance, it is unacceptable to modify versioned releases. If it's appropriate, document the offending (% style="color:#e74c3c" %)version(%%) and inform your users of the problem so that they are aware of the offending (% style="color:#e74c3c" %)version(%%).
123 123  
124 -**What if I inadvertently alter the public artefact in a way that is not compliant with the version number change (i.e. the modification incorrectly introduces a major breaking change in a patch release)?**
124 +**What if I inadvertently alter the public [[artefact>>doc:xwiki:Glossary.Artefact.WebHome]] in a way that is not compliant with the (% style="color:#e74c3c" %)version(%%) number change (i.e. the modification incorrectly introduces a major breaking change in a patch release)?**
125 125  
126 -Use your best judgement. If you have a huge audience that will be drastically impacted by changing the behaviour back to what the public [[artefact>>doc:Glossary.Artefact.WebHome]] intended, then it may be best to perform a major [[version>>doc:Glossary.Version.WebHome]] release, even though the property change could strictly be considered a patch release. Remember, [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] 3.0.0 Semantic Versioning is all about conveying meaning by how the [[version>>doc:Glossary.Version.WebHome]] number changes. If these changes are important to your users, use the [[version>>doc:Glossary.Version.WebHome]] number to inform them.
126 +Use your best judgement. If you have a huge audience that will be drastically impacted by changing the behaviour back to what the public [[artefact>>doc:xwiki:Glossary.Artefact.WebHome]] intended, then it may be best to perform a major (% style="color:#e74c3c" %)version(%%) release, even though the property change could strictly be considered a patch release. Remember, [[SDMX>>doc:xwiki:Glossary.Statistical data and metadata exchange.WebHome]] 3.0.0 Semantic Versioning is all about conveying meaning by how the (% style="color:#e74c3c" %)version(%%) number changes. If these changes are important to your users, use the (% style="color:#e74c3c" %)version(%%) number to inform them.
127 127  
128 128  **How should I handle deprecating elements?**
129 129  
130 -Deprecating existing elements is a normal part of data modelling and is often required to make forward progress or follow history (changing classifications, evolving [[reference areas>>doc:Glossary.Reference area.WebHome]]). When you deprecate part of your stable [[artefact>>doc:Glossary.Artefact.WebHome]], you should issue a new minor [[version>>doc:Glossary.Version.WebHome]] with the deprecation in place (e.g. add the new country [[code>>doc:Glossary.Code.WebHome]] but still keep the old country [[code>>doc:Glossary.Code.WebHome]]) and with a "CHANGELOG" [[annotation>>doc:Glossary.Annotation.WebHome]] announcing the deprecation (e.g. the intention to remove the old country [[code>>doc:Glossary.Code.WebHome]] in a future [[version>>doc:Glossary.Version.WebHome]]) . Before you completely remove the functionality in a new major release there should be at least one minor release that contains the deprecation so that users can smoothly transition to the new [[artefact>>doc:Glossary.Artefact.WebHome]].
130 +Deprecating existing elements is a normal part of data modelling and is often required to make forward progress or follow history (changing classifications, evolving [[reference areas>>doc:xwiki:Glossary.Reference area.WebHome]]). When you deprecate part of your stable [[artefact>>doc:xwiki:Glossary.Artefact.WebHome]], you should issue a new minor (% style="color:#e74c3c" %)version(%%) with the deprecation in place (e.g. add the new country [[code>>doc:xwiki:Glossary.Code.WebHome]] but still keep the old country [[code>>doc:xwiki:Glossary.Code.WebHome]]) and with a "CHANGELOG" [[annotation>>doc:xwiki:Glossary.Annotation.WebHome]] announcing the deprecation (e.g. the intention to remove the old country [[code>>doc:xwiki:Glossary.Code.WebHome]] in a future (% style="color:#e74c3c" %)version(%%)) . Before you completely remove the functionality in a new major release there should be at least one minor release that contains the deprecation so that users can smoothly transition to the new [[artefact>>doc:xwiki:Glossary.Artefact.WebHome]].
131 131  
132 -**Does SDMX 3.0.0 Semantic Versioning have a size limit on the version string?**
132 +**Does SDMX 3.0.0 Semantic Versioning have a size limit on the (% style="color:#e74c3c" %)version(%%) string?**
133 133  
134 -No, but use good judgement. A 255 character [[version>>doc:Glossary.Version.WebHome]] string is probably overkill, for example. In addition, specific [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] implementations may impose their own limits on the size of the string. Remember, it is generally recommended to use the standard extension "-draft".
134 +No, but use good judgement. A 255 character (% style="color:#e74c3c" %)version(%%) string is probably overkill, for example. In addition, specific [[SDMX>>doc:xwiki:Glossary.Statistical data and metadata exchange.WebHome]] implementations may impose their own limits on the size of the string. Remember, it is generally recommended to use the standard extension "-draft".
135 135  
136 -**Is "v1.2.3" a semantic version?**
136 +**Is "v1.2.3" a semantic (% style="color:#e74c3c" %)version(%%)?**
137 137  
138 -No, "v1.2.3" is not a semantic version. The semantic version is "1.2.3".
138 +No, "v1.2.3" is not a semantic (% style="color:#e74c3c" %)version(%%). The semantic (% style="color:#e74c3c" %)version(%%) is "1.2.3".
139 139  
140 140  **Is there a suggested regular expression (RegEx) to check an SDMX 3.0.0 Semantic Versioning string?**
141 141  
... ... @@ -143,38 +143,38 @@
143 143  
144 144  One with named groups for those systems that support them (PCRE [Perl Compatible Regular Expressions, i.e. Perl, PHP and R], Python and Go).
145 145  
146 -Reduced version (without original SemVer "build metadata") from: [[__https:~~/~~/regex101.com/r/Ly7O1x/3/__>>https://regex101.com/r/Ly7O1x/3/]]
146 +Reduced (% style="color:#e74c3c" %)version(%%) (without original SemVer "build metadata") from: [[__https:~~/~~/regex101.com/r/Ly7O1x/3/__https:~~/~~/regex101.com/r/Ly7O1x/3/>>https://https:regex101.comrLy7O1x3https:regex101.comrLy7O1x3]]
147 147  
148 148  > ^(?P<major>0|[1-9]\d*)\.(?P<minor>0|[1-9]\d*)\.(?P<patch>0|[1-9]\d*)(?:-(?P<extension>(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?$
149 149  
150 150  And one with numbered capture groups instead (so cg1 = major, cg2 = minor, cg3 = patch and cg4 = extension) that is compatible with ECMA Script (JavaScript), PCRE (Perl Compatible Regular Expressions, i.e. Perl, PHP and R), Python and Go.
151 151  
152 -Reduced version (without original SemVer "build metadata") from: [[__https:~~/~~/regex101.com/r/vkijKf/1/__>>https://regex101.com/r/vkijKf/1/]]
152 +Reduced (% style="color:#e74c3c" %)version(%%) (without original SemVer "build metadata") from: [[__https:~~/~~/regex101.com/r/vkijKf/1/__https:~~/~~/regex101.com/r/vkijKf/1/>>https://https:regex101.comrvkijKf1https:regex101.comrvkijKf1]]
153 153  
154 154  > ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?$
155 155  
156 156  **Must I adopt semantic versioning rules when switching to SDMX 3.0?**
157 157  
158 -No. If backwards compatibility with pre-existing tools and processes is required, then it is possible to continue using the previous versioning scheme (with up to two version parts MAJOR.MINOR). Semantic versioning is indicated only for those use cases where a proper [[artefact>>doc:Glossary.Artefact.WebHome]] versioning is required. If versioning does not apply to some or all of your [[artefacts>>doc:Glossary.Artefact.WebHome]], then rather migrate to non-versioned [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] 3.0 [[artefacts>>doc:Glossary.Artefact.WebHome]].
158 +No. If backwards compatibility with pre-existing tools and processes is required, then it is possible to continue using the previous versioning scheme (with up to two (% style="color:#e74c3c" %)version(%%) parts MAJOR.MINOR). Semantic versioning is indicated only for those use cases where a proper [[artefact>>doc:xwiki:Glossary.Artefact.WebHome]] versioning is required. If versioning does not apply to some or all of your [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]], then rather migrate to non-versioned [[SDMX>>doc:xwiki:Glossary.Statistical data and metadata exchange.WebHome]] 3.0 [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]].
159 159  
160 160  **May I mix artefacts that follow semantic versioning with artefacts that don't?**
161 161  
162 -[[Artefacts>>doc:Glossary.Artefact.WebHome]] that are not (semantically) versioned may reference [[artefacts>>doc:Glossary.Artefact.WebHome]] that are semantically versioned, but those are fully safe to use only when not extended. However, the reverse is not true: non-semantically-versioned [[artefacts>>doc:Glossary.Artefact.WebHome]] do not offer change guarantees, and, therefore, should not be referenced by semantically versioned [[artefacts>>doc:Glossary.Artefact.WebHome]].
162 +[[Artefacts>>doc:xwiki:Glossary.Artefact.WebHome]] that are not (semantically) versioned may reference [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]] that are semantically versioned, but those are fully safe to use only when not extended. However, the reverse is not true: non-semantically-versioned [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]] do not offer change guarantees, and, therefore, should not be referenced by semantically versioned [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]].
163 163  
164 164  **I have plenty of artefacts. I'm happy with my current versioning policy and I don't want to use SemVer! Can I still migrate to SDMX 3.0, and if so, what do I need to do?**
165 165  
166 -Yes, of course, you can. The introduction of semantic versioning is done in a way which is largely backward compatible with previous versions of the standard, so you can keep your existing 2-digit version numbers (1.0, 1.1, 2.0, etc.) if that is required by your current tools and processes. However, if not using SemVer then pre-[[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] 3.0 final [[artefacts>>doc:Glossary.Artefact.WebHome]] will be migrated as non-final and mutable in [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] 3.0. There are also many good reasons to move to SemVer, and the migration is encouraged. Be assured that there will be tools out there that will assist you doing this in an efficient and convenient way.
166 +Yes, of course, you can. The introduction of semantic versioning is done in a way which is largely backward compatible with previous (% style="color:#e74c3c" %)versions(%%) of the standard, so you can keep your existing 2-digit (% style="color:#e74c3c" %)version(%%) numbers (1.0, 1.1, 2.0, etc.) if that is required by your current tools and processes. However, if not using SemVer then pre-[[SDMX>>doc:xwiki:Glossary.Statistical data and metadata exchange.WebHome]] 3.0 final [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]] will be migrated as non-final and mutable in [[SDMX>>doc:xwiki:Glossary.Statistical data and metadata exchange.WebHome]] 3.0. There are also many good reasons to move to SemVer, and the migration is encouraged. Be assured that there will be tools out there that will assist you doing this in an efficient and convenient way.
167 167  
168 168  **I have plenty of artefacts versioned 'X.Y'. I want to make some of them immutable, and enjoy the benefits provided by semantic versioning. Some other artefacts however must remain mutable (i.e. non final). However, in both cases, I'd like adopt the semantic versioning. What do I need to do?**
169 169  
170 -For [[artefacts>>doc:Glossary.Artefact.WebHome]] that will be made immutable and are therefore safe to use, simply append a '.0' to the current version (use X.Y.0) when migrating to Semantic Versioning. E.g., if the version of your [[artefact>>doc:Glossary.Artefact.WebHome]] is currently 1.10, then migrate to 1.10.0.
170 +For [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]] that will be made immutable and are therefore safe to use, simply append a '.0' to the current (% style="color:#e74c3c" %)version(%%) (use X.Y.0) when migrating to Semantic Versioning. E.g., if the (% style="color:#e74c3c" %)version(%%) of your [[artefact>>doc:xwiki:Glossary.Artefact.WebHome]] is currently 1.10, then migrate to 1.10.0.
171 171  
172 -For [[artefacts>>doc:Glossary.Artefact.WebHome]] that remain mutable, and therefore do not bring the guarantees of semantic versioning, if you want to benefit from the advantages of semantic versioning, then simply append '.0-notfinal' to the version string. So, if the version of your [[artefact>>doc:Glossary.Artefact.WebHome]] is currently 1.10, use 1.10.0-notfinal instead. Indeed, other extensions can be used depending on your use case.
172 +For [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]] that remain mutable, and therefore do not bring the guarantees of semantic versioning, if you want to benefit from the advantages of semantic versioning, then simply append '.0-notfinal' to the (% style="color:#e74c3c" %)version(%%) string. So, if the (% style="color:#e74c3c" %)version(%%) of your [[artefact>>doc:xwiki:Glossary.Artefact.WebHome]] is currently 1.10, use 1.10.0-notfinal instead. Indeed, other extensions can be used depending on your use case.
173 173  
174 174  **I have adopted SDMX 3.0 with the semantic versioning conventions for the version strings of all my artefacts, regardless of whether these are stable (e.g. 1.0.0) or unstable (e.g. 1.0.0-notfinal, 1.0.0-draft, etc.). However, I still receive artefacts from organizations that have not yet adopted SemVer conventions for the version strings. How should I treat these?**
175 175  
176 -The only [[artefacts>>doc:Glossary.Artefact.WebHome]] that are safe to use, are those that are semantically versioned. Starting with [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] 3.0, these [[artefacts>>doc:Glossary.Artefact.WebHome]] MUST use the SEMVER version string to indicate this fact and the version string of these [[artefacts>>doc:Glossary.Artefact.WebHome]] MUST be expressed as X.Y.Z (e.g. 2.1.0). Extended versions bring some limited guarantees for changes.
176 +The only [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]] that are safe to use, are those that are semantically versioned. Starting with [[SDMX>>doc:xwiki:Glossary.Statistical data and metadata exchange.WebHome]] 3.0, these [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]] MUST use the SEMVER (% style="color:#e74c3c" %)version(%%) string to indicate this fact and the (% style="color:#e74c3c" %)version(%%) string of these [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]] MUST be expressed as X.Y.Z (e.g. 2.1.0). Extended (% style="color:#e74c3c" %)versions(%%) bring some limited guarantees for changes.
177 177  
178 -All other [[artefacts>>doc:Glossary.Artefact.WebHome]] are in principle unsafe. They might be safe in practice but the [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] standard does not bring any guarantees in that respect, and these [[artefacts>>doc:Glossary.Artefact.WebHome]] may change in unpredictable ways.
178 +All other [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]] are in principle unsafe. They might be safe in practice but the [[SDMX>>doc:xwiki:Glossary.Statistical data and metadata exchange.WebHome]] standard does not bring any guarantees in that respect, and these [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]] may change in unpredictable ways.
179 179  
180 -In practice, the migration approach will often mirror the way in which organisations have migrated between earlier [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] versions. Rarely, the new data models used mixed [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] standard versions in their dependencies, and if they did then standard conversions were put in place. A typical method is to first migrate the re-used [[artefacts>>doc:Glossary.Artefact.WebHome]] from the previous [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] version to [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] 3.0 and while doing so to apply the appropriate new semantic [[version>>doc:Glossary.Version.WebHome]] string. From that point onwards, you can enjoy the advantages of the new [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] versioning features for all those [[artefacts>>doc:Glossary.Artefact.WebHome]] that require appropriate versioning.
180 +In practice, the migration approach will often mirror the way in which organisations have migrated between earlier [[SDMX>>doc:xwiki:Glossary.Statistical data and metadata exchange.WebHome]] (% style="color:#e74c3c" %)versions(%%). Rarely, the new data models used mixed [[SDMX>>doc:xwiki:Glossary.Statistical data and metadata exchange.WebHome]] standard (% style="color:#e74c3c" %)versions(%%) in their dependencies, and if they did then standard conversions were put in place. A typical method is to first migrate the re-used [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]] from the previous [[SDMX>>doc:xwiki:Glossary.Statistical data and metadata exchange.WebHome]] (% style="color:#e74c3c" %)version(%%) to [[SDMX>>doc:xwiki:Glossary.Statistical data and metadata exchange.WebHome]] 3.0 and while doing so to apply the appropriate new semantic (% style="color:#e74c3c" %)version(%%) string. From that point onwards, you can enjoy the advantages of the new [[SDMX>>doc:xwiki:Glossary.Statistical data and metadata exchange.WebHome]] versioning features for all those [[artefacts>>doc:xwiki:Glossary.Artefact.WebHome]] that require appropriate versioning.
SKMS.Methodology.Code.MethodologyClass[0]
Index
... ... @@ -1,1 +1,0 @@
1 -14
SUZ.Methodology.Code.MethodologyClass[0]
index
... ... @@ -1,0 +1,1 @@
1 +14