Skip to Content
Last modified by Artur on 2025/09/10 11:19
From version 2.2
edited by Helena
on 2025/06/16 15:44
Change comment: There is no comment for this version
To version 2.3
edited by Helena
on 2025/06/16 15:46
Change comment: There is no comment for this version

Summary

Details

Page properties
Content
... ... @@ -98,7 +98,7 @@
98 98  
99 99  == 14.6 FAQ for Semantic Versioning ==
100 100  
101 -**My organisation is new to [[SDMX>>doc:sdmx:Glossary.Statistical data and metadata exchange.WebHome]] and starts to implement 3.0 or starts to implement a new process fully based on [[SDMX>>doc:sdmx:Glossary.Statistical data and metadata exchange.WebHome]] 3.0. Which versioning scheme should be used?**
101 +**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?**
102 102  
103 103  If all counterparts involved in the process and all tools used for its implementation are [[SDMX>>doc:sdmx:Glossary.Statistical data and metadata exchange.WebHome]] 3.0-ready, then it is recommended to:
104 104  
... ... @@ -121,17 +121,17 @@
121 121  
122 122  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.
123 123  
124 -**Documenting the (% style="color:#e74c3c" %)version(%%) changes in an [[artefact>>doc:sdmx:Glossary.Artefact.WebHome]]'s [[annotation>>doc:sdmx:Glossary.Annotation.WebHome]] of type "CHANGELOG" is too much work!**
124 +**Documenting the version changes in an artefact's annotation of type "CHANGELOG" is too much work!**
125 125  
126 126  It is your responsibility as a professional modeller to properly document the [[artefacts>>doc:sdmx: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:sdmx:Glossary.Artefact.WebHome]] are safe to reuse. In the long run, [[SDMX>>doc:sdmx:Glossary.Statistical data and metadata exchange.WebHome]] 3.0 Semantic Versioning can keep everyone and everything running smoothly.
127 127  
128 128  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(%%).
129 129  
130 -**What do I do if I accidentally release a backwards incompatible change as a minor (% style="color:#e74c3c" %)version(%%)?**
130 +**What do I do if I accidentally release a backwards incompatible change as a minor version?**
131 131  
132 132  As soon as you realise that you've broken the [[SDMX>>doc:sdmx: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(%%).
133 133  
134 -**What if I inadvertently alter the public [[artefact>>doc:sdmx: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)?**
134 +**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)?**
135 135  
136 136  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:sdmx: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:sdmx: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.
137 137  
... ... @@ -139,15 +139,15 @@
139 139  
140 140  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:sdmx:Glossary.Reference area.WebHome]]). When you deprecate part of your stable [[artefact>>doc:sdmx: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:sdmx:Glossary.Code.WebHome]] but still keep the old country [[code>>doc:sdmx:Glossary.Code.WebHome]]) and with a "CHANGELOG" [[annotation>>doc:sdmx:Glossary.Annotation.WebHome]] announcing the deprecation (e.g. the intention to remove the old country [[code>>doc:sdmx: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:sdmx:Glossary.Artefact.WebHome]].
141 141  
142 -**Does [[SDMX>>doc:sdmx:Glossary.Statistical data and metadata exchange.WebHome]] 3.0.0 Semantic Versioning have a size limit on the (% style="color:#e74c3c" %)version(%%) string?**
142 +**Does SDMX 3.0.0 Semantic Versioning have a size limit on the version string?**
143 143  
144 144  No, but use good judgement. A 255 character (% style="color:#e74c3c" %)version(%%) string is probably overkill, for example. In addition, specific [[SDMX>>doc:sdmx: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".
145 145  
146 -**Is "v1.2.3" a semantic (% style="color:#e74c3c" %)version(%%)?**
146 +**Is "v1.2.3" a semantic version?**
147 147  
148 148  No, "v1.2.3" is not a semantic (% style="color:#e74c3c" %)version(%%). The semantic (% style="color:#e74c3c" %)version(%%) is "1.2.3".
149 149  
150 -**Is there a suggested regular expression (RegEx) to check an [[SDMX>>doc:sdmx:Glossary.Statistical data and metadata exchange.WebHome]] 3.0.0 Semantic Versioning string?**
150 +**Is there a suggested regular expression (RegEx) to check an SDMX 3.0.0 Semantic Versioning string?**
151 151  
152 152  There are two:
153 153