Debian Codegraph @

doc/source/user/semver.rst

raw
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/