| 1 |
Linux/Python Compatible Semantic Versioning 3.0.0 |
| 2 |
================================================= |
| 3 |
|
| 4 |
This is a fork of Semantic Versioning 2.0. The specific changes have to do |
| 5 |
with the format of pre-release and build labels, specifically to make them |
| 6 |
not confusing when co-existing with Linux distribution packaging and Python |
| 7 |
packaging. Inspiration for the format of the pre-release and build labels |
| 8 |
came from Python's PEP440. |
| 9 |
|
| 10 |
Changes vs SemVer 2.0 |
| 11 |
--------------------- |
| 12 |
|
| 13 |
#. dev versions are defined. These are extremely useful when |
| 14 |
dealing with CI and CD systems when 'every commit is a release' is not |
| 15 |
feasible. |
| 16 |
|
| 17 |
#. All versions have been made PEP-440 compatible, because of our deep |
| 18 |
roots in Python: |
| 19 |
|
| 20 |
- Pre-release versions are now separated by . not -, and use a/b/c |
| 21 |
rather than alpha/beta etc. |
| 22 |
- Alpha version are prefixed by a 0 such as: ``2.0.0.0a1`` instead of |
| 23 |
``2.0.0.a1`` for version '2.0.0 alpha 1'. Please note dev version tag |
| 24 |
does not have a leading 0, as is ``2.0.0.0a2.dev1``. |
| 25 |
|
| 26 |
Summary |
| 27 |
------- |
| 28 |
|
| 29 |
Given a version number MAJOR.MINOR.PATCH, |
| 30 |
increment the: |
| 31 |
|
| 32 |
#. MAJOR version when you make incompatible API changes, |
| 33 |
#. MINOR version when you add functionality in a backwards-compatible |
| 34 |
manner, and |
| 35 |
#. PATCH version when you make backwards-compatible bug fixes. |
| 36 |
|
| 37 |
Introduction |
| 38 |
------------ |
| 39 |
|
| 40 |
In the world of software management there exists a dread place called |
| 41 |
"dependency hell." The bigger your system grows and the more packages |
| 42 |
you integrate into your software, the more likely you are to find |
| 43 |
yourself, one day, in this pit of despair. |
| 44 |
|
| 45 |
In systems with many dependencies, releasing new package versions can |
| 46 |
quickly become a nightmare. If the dependency specifications are too |
| 47 |
tight, you are in danger of version lock (the inability to upgrade a |
| 48 |
package without having to release new versions of every dependent |
| 49 |
package). If dependencies are specified too loosely, you will inevitably |
| 50 |
be bitten by version promiscuity (assuming compatibility with more |
| 51 |
future versions than is reasonable). Dependency hell is where you are |
| 52 |
when version lock and/or version promiscuity prevent you from easily and |
| 53 |
safely moving your project forward. |
| 54 |
|
| 55 |
As a solution to this problem, I propose a simple set of rules and |
| 56 |
requirements that dictate how version numbers are assigned and |
| 57 |
incremented. These rules are based on but not necessarily limited to |
| 58 |
pre-existing widespread common practices in use in both closed and |
| 59 |
open-source software. For this system to work, you first need to declare |
| 60 |
a public API. This may consist of documentation or be enforced by the |
| 61 |
code itself. Regardless, it is important that this API be clear and |
| 62 |
precise. Once you identify your public API, you communicate changes to |
| 63 |
it with specific increments to your version number. Consider a version |
| 64 |
format of X.Y.Z (Major.Minor.Patch). Bug fixes not affecting the API |
| 65 |
increment the patch version, backwards compatible API additions/changes |
| 66 |
increment the minor version, and backwards incompatible API changes |
| 67 |
increment the major version. |
| 68 |
|
| 69 |
I call this system "Semantic Versioning." Under this scheme, version |
| 70 |
numbers and the way they change convey meaning about the underlying code |
| 71 |
and what has been modified from one version to the next. |
| 72 |
|
| 73 |
Semantic Versioning Specification (SemVer) |
| 74 |
------------------------------------------ |
| 75 |
|
| 76 |
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", |
| 77 |
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this |
| 78 |
document are to be interpreted as described in `RFC |
| 79 |
2119 <http://tools.ietf.org/html/rfc2119>`__. |
| 80 |
|
| 81 |
#. Software using Semantic Versioning MUST declare a public API. This |
| 82 |
API could be declared in the code itself or exist strictly in |
| 83 |
documentation. However it is done, it should be precise and |
| 84 |
comprehensive. |
| 85 |
|
| 86 |
#. A normal version number MUST take the form X.Y.Z where X, Y, and Z |
| 87 |
are non-negative integers, and MUST NOT contain leading zeroes. X is |
| 88 |
the major version, Y is the minor version, and Z is the patch |
| 89 |
version. Each element MUST increase numerically. For instance: 1.9.0 |
| 90 |
-> 1.10.0 -> 1.11.0. |
| 91 |
|
| 92 |
#. Once a versioned package has been released, the contents of that |
| 93 |
version MUST NOT be modified. Any modifications MUST be released as |
| 94 |
a new version. |
| 95 |
|
| 96 |
#. Major version zero (0.y.z) is for initial development. Anything may |
| 97 |
change at any time. The public API should not be considered stable. |
| 98 |
|
| 99 |
#. Version 1.0.0 defines the public API. The way in which the version |
| 100 |
number is incremented after this release is dependent on this public |
| 101 |
API and how it changes. |
| 102 |
|
| 103 |
#. Patch version Z (x.y.Z \| x > 0) MUST be incremented if only |
| 104 |
backwards compatible bug fixes are introduced. A bug fix is defined |
| 105 |
as an internal change that fixes incorrect behavior. |
| 106 |
|
| 107 |
#. Minor version Y (x.Y.z \| x > 0) MUST be incremented if new, |
| 108 |
backwards compatible functionality is introduced to the public API. |
| 109 |
It MUST be incremented if any public API functionality is marked as |
| 110 |
deprecated. It MAY be incremented if substantial new functionality |
| 111 |
or improvements are introduced within the private code. It MAY |
| 112 |
include patch level changes. Patch version MUST be reset to 0 when |
| 113 |
minor version is incremented. |
| 114 |
|
| 115 |
#. Major version X (X.y.z \| X > 0) MUST be incremented if any |
| 116 |
backwards incompatible changes are introduced to the public API. It |
| 117 |
MAY also include minor and patch level changes. Patch and minor |
| 118 |
version MUST be reset to 0 when major version is incremented. |
| 119 |
|
| 120 |
#. A pre-release version MAY be denoted by appending a dot |
| 121 |
separated identifier immediately following the patch version. |
| 122 |
The identifier MUST comprise only a, b, c followed by non-negative |
| 123 |
integer value. The identifier MUST NOT be empty. |
| 124 |
Pre-release versions have a lower precedence than the associated normal |
| 125 |
version. A pre-release version indicates that |
| 126 |
the version is unstable and might not satisfy the intended |
| 127 |
compatibility requirements as denoted by its associated normal |
| 128 |
version. Examples: 1.0.0.0a1, 1.0.0.0b99, 1.0.0.0c1000. |
| 129 |
|
| 130 |
#. A development version MAY be denoted by appending a dot separated |
| 131 |
identifier immediately following the patch version. |
| 132 |
The identifier MUST comprise the string dev followed by non-negative |
| 133 |
integer value. The identifier MUST NOT be empty. Development versions |
| 134 |
have a lower precedence than the associated normal version or pre-release |
| 135 |
version. A development version is a completely unsupported and conveys no |
| 136 |
API promises when related to other versions. They are more useful as |
| 137 |
communication vehicles between developers of a community, whereas |
| 138 |
pre-releases, while potentially prone to break still, are intended for |
| 139 |
externally facing communication of not-yet-released ideas. Dev versions |
| 140 |
are not public artifacts and should never be placed in public |
| 141 |
repositories: they are intended as developer-local resources. Examples: |
| 142 |
1.0.0.dev1, 1.0.0.0a1.dev1 |
| 143 |
|
| 144 |
#. git version metadata MAY be denoted by appending a dot separated |
| 145 |
identifier immediately following a development or pre-release version. |
| 146 |
The identifier MUST comprise the character g followed by a seven |
| 147 |
character git short-sha. The sha MUST NOT be empty. git version |
| 148 |
metadata MUST be ignored when determining version precedence. Thus |
| 149 |
two versions that differ only in the git version, have the same |
| 150 |
precedence. Example: 1.0.0.0a1.g95a9beb. |
| 151 |
|
| 152 |
#. Build metadata MAY be denoted by appending a plus sign and a series |
| 153 |
of dot separated identifiers immediately following the patch or |
| 154 |
pre-release version. Identifiers MUST comprise only ASCII |
| 155 |
alphanumerics [0-9A-Za-z]. Identifiers MUST NOT be empty. Build |
| 156 |
metadata MUST be ignored when determining version precedence. Thus |
| 157 |
two versions that differ only in the build metadata, have the same |
| 158 |
precedence. Examples: 1.0.0.0a1+001, 1.0.0+20130313144700, |
| 159 |
1.0.0.0b1+exp.sha.5114f85. |
| 160 |
|
| 161 |
#. Precedence refers to how versions are compared to each other when |
| 162 |
ordered. Precedence MUST be calculated by separating the version |
| 163 |
into major, minor, patch, pre-release, and development identifiers in |
| 164 |
that order (Build metadata does not figure into precedence). Precedence |
| 165 |
is determined by the first difference when comparing each of these |
| 166 |
identifiers from left to right as follows: Major, minor, and patch |
| 167 |
versions are always compared numerically. Example: 1.0.0 < 2.0.0 < |
| 168 |
2.1.0 < 2.1.1. When major, minor, and patch are equal, a pre-release |
| 169 |
version has lower precedence than a normal version. Example: |
| 170 |
1.0.0.0a1 < 1.0.0. When major, minor, patch and pre-release are equal, a |
| 171 |
development version has a lower precedence than a normal version and of a |
| 172 |
pre-release version. Example: 1.0.0.dev1 < 1.0.0 and 1.0.0.dev9 < |
| 173 |
1.0.0.0a1 and 1.0.0.0a1 < 1.0.0.0a2.dev4. Precedence for two pre-release |
| 174 |
versions with the same major, minor, and patch version MUST be determined |
| 175 |
by comparing the identifier to the right of the patch version as follows: |
| 176 |
if the alpha portion matches, the numeric portion is compared in |
| 177 |
numerical sort order. If the alpha portion does not match, the sort order |
| 178 |
is dev < a < b < c. Example: 1.0.0.dev8 < 1.0.0.dev9 < 1.0.0.0a1.dev3 < |
| 179 |
1.0.0.0a1 < 1.0.0.0b2 < 1.0.0.0c1 < 1.0.0. Precedence for dev versions if |
| 180 |
all other components are equal is done by comparing their numeric |
| 181 |
component. If all other components are not equal, predence is determined |
| 182 |
by comparing the other components. |
| 183 |
|
| 184 |
Why Use Semantic Versioning? |
| 185 |
---------------------------- |
| 186 |
|
| 187 |
This is not a new or revolutionary idea. In fact, you probably do |
| 188 |
something close to this already. The problem is that "close" isn't good |
| 189 |
enough. Without compliance to some sort of formal specification, version |
| 190 |
numbers are essentially useless for dependency management. By giving a |
| 191 |
name and clear definition to the above ideas, it becomes easy to |
| 192 |
communicate your intentions to the users of your software. Once these |
| 193 |
intentions are clear, flexible (but not too flexible) dependency |
| 194 |
specifications can finally be made. |
| 195 |
|
| 196 |
A simple example will demonstrate how Semantic Versioning can make |
| 197 |
dependency hell a thing of the past. Consider a library called |
| 198 |
"Firetruck." It requires a Semantically Versioned package named |
| 199 |
"Ladder." At the time that Firetruck is created, Ladder is at version |
| 200 |
3.1.0. Since Firetruck uses some functionality that was first introduced |
| 201 |
in 3.1.0, you can safely specify the Ladder dependency as greater than |
| 202 |
or equal to 3.1.0 but less than 4.0.0. Now, when Ladder version 3.1.1 |
| 203 |
and 3.2.0 become available, you can release them to your package |
| 204 |
management system and know that they will be compatible with existing |
| 205 |
dependent software. |
| 206 |
|
| 207 |
As a responsible developer you will, of course, want to verify that any |
| 208 |
package upgrades function as advertised. The real world is a messy |
| 209 |
place; there's nothing we can do about that but be vigilant. What you |
| 210 |
can do is let Semantic Versioning provide you with a sane way to release |
| 211 |
and upgrade packages without having to roll new versions of dependent |
| 212 |
packages, saving you time and hassle. |
| 213 |
|
| 214 |
If all of this sounds desirable, all you need to do to start using |
| 215 |
Semantic Versioning is to declare that you are doing so and then follow |
| 216 |
the rules. Link to this website from your README so others know the |
| 217 |
rules and can benefit from them. |
| 218 |
|
| 219 |
FAQ |
| 220 |
--- |
| 221 |
|
| 222 |
How should I deal with revisions in the 0.y.z initial development phase? |
| 223 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 224 |
|
| 225 |
The simplest thing to do is start your initial development release at |
| 226 |
0.1.0 and then increment the minor version for each subsequent release. |
| 227 |
|
| 228 |
How do I know when to release 1.0.0? |
| 229 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 230 |
|
| 231 |
If your software is being used in production, it should probably already |
| 232 |
be 1.0.0. If you have a stable API on which users have come to depend, |
| 233 |
you should be 1.0.0. If you're worrying a lot about backwards |
| 234 |
compatibility, you should probably already be 1.0.0. |
| 235 |
|
| 236 |
Doesn't this discourage rapid development and fast iteration? |
| 237 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 238 |
|
| 239 |
Major version zero is all about rapid development. If you're changing |
| 240 |
the API every day you should either still be in version 0.y.z or on a |
| 241 |
separate development branch working on the next major version. |
| 242 |
|
| 243 |
If even the tiniest backwards incompatible changes to the public API require a major version bump, won't I end up at version 42.0.0 very rapidly? |
| 244 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 245 |
|
| 246 |
This is a question of responsible development and foresight. |
| 247 |
Incompatible changes should not be introduced lightly to software that |
| 248 |
has a lot of dependent code. The cost that must be incurred to upgrade |
| 249 |
can be significant. Having to bump major versions to release |
| 250 |
incompatible changes means you'll think through the impact of your |
| 251 |
changes, and evaluate the cost/benefit ratio involved. |
| 252 |
|
| 253 |
Documenting the entire public API is too much work! |
| 254 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 255 |
|
| 256 |
It is your responsibility as a professional developer to properly |
| 257 |
document software that is intended for use by others. Managing software |
| 258 |
complexity is a hugely important part of keeping a project efficient, |
| 259 |
and that's hard to do if nobody knows how to use your software, or what |
| 260 |
methods are safe to call. In the long run, Semantic Versioning, and the |
| 261 |
insistence on a well defined public API can keep everyone and everything |
| 262 |
running smoothly. |
| 263 |
|
| 264 |
What do I do if I accidentally release a backwards incompatible change as a minor version? |
| 265 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 266 |
|
| 267 |
As soon as you realize that you've broken the Semantic Versioning spec, |
| 268 |
fix the problem and release a new minor version that corrects the |
| 269 |
problem and restores backwards compatibility. Even under this |
| 270 |
circumstance, it is unacceptable to modify versioned releases. If it's |
| 271 |
appropriate, document the offending version and inform your users of the |
| 272 |
problem so that they are aware of the offending version. |
| 273 |
|
| 274 |
What should I do if I update my own dependencies without changing the public API? |
| 275 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 276 |
|
| 277 |
That would be considered compatible since it does not affect the public |
| 278 |
API. Software that explicitly depends on the same dependencies as your |
| 279 |
package should have their own dependency specifications and the author |
| 280 |
will notice any conflicts. Determining whether the change is a patch |
| 281 |
level or minor level modification depends on whether you updated your |
| 282 |
dependencies in order to fix a bug or introduce new functionality. I |
| 283 |
would usually expect additional code for the latter instance, in which |
| 284 |
case it's obviously a minor level increment. |
| 285 |
|
| 286 |
What if I inadvertently alter the public API in a way that is not compliant with the version number change (i.e. the code incorrectly introduces a major breaking change in a patch release) |
| 287 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 288 |
|
| 289 |
Use your best judgment. If you have a huge audience that will be |
| 290 |
drastically impacted by changing the behavior back to what the public |
| 291 |
API intended, then it may be best to perform a major version release, |
| 292 |
even though the fix could strictly be considered a patch release. |
| 293 |
Remember, Semantic Versioning is all about conveying meaning by how the |
| 294 |
version number changes. If these changes are important to your users, |
| 295 |
use the version number to inform them. |
| 296 |
|
| 297 |
How should I handle deprecating functionality? |
| 298 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 299 |
|
| 300 |
Deprecating existing functionality is a normal part of software |
| 301 |
development and is often required to make forward progress. When you |
| 302 |
deprecate part of your public API, you should do two things: (1) update |
| 303 |
your documentation to let users know about the change, (2) issue a new |
| 304 |
minor release with the deprecation in place. Before you completely |
| 305 |
remove the functionality in a new major release there should be at least |
| 306 |
one minor release that contains the deprecation so that users can |
| 307 |
smoothly transition to the new API. |
| 308 |
|
| 309 |
Does SemVer have a size limit on the version string? |
| 310 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 311 |
|
| 312 |
No, but use good judgment. A 255 character version string is probably |
| 313 |
overkill, for example. Also, specific systems may impose their own |
| 314 |
limits on the size of the string. |
| 315 |
|
| 316 |
About |
| 317 |
----- |
| 318 |
|
| 319 |
The Linux/Python Compatible Semantic Versioning specification is maintained |
| 320 |
by the `OpenStack <http://openstack.org>`_ project. |
| 321 |
|
| 322 |
It is based on The Semantic Versioning specification, which was |
| 323 |
authored by `Tom Preston-Werner <http://tom.preston-werner.com>`__, |
| 324 |
with inputs from `PEP 440 <http://www.python.org/dev/peps/pep-0440/>`_ |
| 325 |
|
| 326 |
If you'd like to leave feedback, please `open an issue |
| 327 |
<https://bugs.launchpad.net/pbr/+filebug>`_. |
| 328 |
|
| 329 |
License |
| 330 |
------- |
| 331 |
|
| 332 |
Creative Commons - CC BY 3.0 http://creativecommons.org/licenses/by/3.0/ |