|
1
|
<!doctype html>
|
|
2
|
<html>
|
|
3
|
<head>
|
|
4
|
<meta charset="utf-8">
|
|
5
|
<title>Semantic Versioning 1.0.0-rc.1</title>
|
|
6
|
<meta name="author" content="Tom Preston-Werner">
|
|
7
|
<link rel="stylesheet" href="/css/main.css">
|
|
8
|
</head>
|
|
9
|
<body>
|
|
10
|
<h1>Semantic Versioning 1.0.0-rc.1</h1>
|
|
11
|
|
|
12
|
<p>In the world of software management there exists a dread place called
|
|
13
|
"dependency hell." The bigger your system grows and the more packages you
|
|
14
|
integrate into your software, the more likely you are to find yourself, one
|
|
15
|
day, in this pit of despair.</p>
|
|
16
|
|
|
17
|
<p>In systems with many dependencies, releasing new package versions can quickly
|
|
18
|
become a nightmare. If the dependency specifications are too tight, you are in
|
|
19
|
danger of version lock (the inability to upgrade a package without having to
|
|
20
|
release new versions of every dependent package). If dependencies are
|
|
21
|
specified too loosely, you will inevitably be bitten by version promiscuity
|
|
22
|
(assuming compatibility with more future versions than is reasonable).
|
|
23
|
Dependency hell is where you are when version lock and/or version promiscuity
|
|
24
|
prevent you from easily and safely moving your project forward.</p>
|
|
25
|
|
|
26
|
<p>As a solution to this problem, I propose a simple set of rules and
|
|
27
|
requirements that dictate how version numbers are assigned and incremented.
|
|
28
|
For this system to work, you first need to declare a public API. This may
|
|
29
|
consist of documentation or be enforced by the code itself. Regardless, it is
|
|
30
|
important that this API be clear and precise. Once you identify your public
|
|
31
|
API, you communicate changes to it with specific increments to your version
|
|
32
|
number. Consider a version format of X.Y.Z (Major.Minor.Patch). Bug fixes not
|
|
33
|
affecting the API increment the patch version, backwards compatible API
|
|
34
|
additions/changes increment the minor version, and backwards incompatible API
|
|
35
|
changes increment the major version.</p>
|
|
36
|
|
|
37
|
<p>I call this system "Semantic Versioning." Under this scheme, version numbers
|
|
38
|
and the way they change convey meaning about the underlying code and what has
|
|
39
|
been modified from one version to the next.</p>
|
|
40
|
|
|
41
|
<h2>Semantic Versioning Specification (SemVer)</h2>
|
|
42
|
|
|
43
|
<p>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
|
|
44
|
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
|
|
45
|
interpreted as described in RFC 2119.</p>
|
|
46
|
|
|
47
|
<ol>
|
|
48
|
<li><p>Software using Semantic Versioning MUST declare a public API. This API
|
|
49
|
could be declared in the code itself or exist strictly in documentation.
|
|
50
|
However it is done, it should be precise and comprehensive.</p></li>
|
|
51
|
<li><p>A normal version number MUST take the form X.Y.Z where X, Y, and Z are
|
|
52
|
non-negative integers. X is the major version, Y is the minor version, and Z
|
|
53
|
is the patch version. Each element MUST increase numerically by increments of
|
|
54
|
one. For instance: 1.9.0 -> 1.10.0 -> 1.11.0.</p></li>
|
|
55
|
<li><p>When a major version number is incremented, the minor version and patch
|
|
56
|
version MUST be reset to zero. When a minor version number is incremented, the
|
|
57
|
patch version MUST be reset to zero. For instance: 1.1.3 -> 2.0.0 and 2.1.7 ->
|
|
58
|
2.2.0.</p></li>
|
|
59
|
<li><p>Once a versioned package has been released, the contents of that version
|
|
60
|
MUST NOT be modified. Any modifications must be released as a new version.</p></li>
|
|
61
|
<li><p>Major version zero (0.y.z) is for initial development. Anything may change
|
|
62
|
at any time. The public API should not be considered stable.</p></li>
|
|
63
|
<li><p>Version 1.0.0 defines the public API. The way in which the version number
|
|
64
|
is incremented after this release is dependent on this public API and how it
|
|
65
|
changes.</p></li>
|
|
66
|
<li><p>Patch version Z (x.y.Z | x > 0) MUST be incremented if only backwards
|
|
67
|
compatible bug fixes are introduced. A bug fix is defined as an internal
|
|
68
|
change that fixes incorrect behavior.</p></li>
|
|
69
|
<li><p>Minor version Y (x.Y.z | x > 0) MUST be incremented if new, backwards
|
|
70
|
compatible functionality is introduced to the public API. It MUST be
|
|
71
|
incremented if any public API functionality is marked as deprecated. It MAY be
|
|
72
|
incremented if substantial new functionality or improvements are introduced
|
|
73
|
within the private code. It MAY include patch level changes. Patch version
|
|
74
|
MUST be reset to 0 when minor version is incremented.</p></li>
|
|
75
|
<li><p>Major version X (X.y.z | X > 0) MUST be incremented if any backwards
|
|
76
|
incompatible changes are introduced to the public API. It MAY include minor
|
|
77
|
and patch level changes. Patch and minor version MUST be reset to 0 when major
|
|
78
|
version is incremented.</p></li>
|
|
79
|
<li><p>A pre-release version MAY be denoted by appending a dash and a series of
|
|
80
|
dot separated identifiers immediately following the patch version. Identifiers
|
|
81
|
MUST be comprised of only ASCII alphanumerics and dash [0-9A-Za-z-].
|
|
82
|
Pre-release versions satisfy but have a lower precedence than the associated
|
|
83
|
normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7,
|
|
84
|
1.0.0-x.7.z.92.</p></li>
|
|
85
|
<li><p>A build version MAY be denoted by appending a plus sign and a series of dot
|
|
86
|
separated identifiers immediately following the patch version or pre-release
|
|
87
|
version. Identifiers MUST be comprised of only ASCII alphanumerics and dash
|
|
88
|
[0-9A-Za-z-]. Build versions satisfy and have a higher precedence than the
|
|
89
|
associated normal version. Examples: 1.0.0+build.1, 1.3.7+build.11.e0f985a.</p></li>
|
|
90
|
<li><p>Precedence MUST be calculated by separating the version into major, minor,
|
|
91
|
patch, pre-release, and build identifiers in that order. Major, minor, and
|
|
92
|
patch versions are always compared numerically. Pre-release and build version
|
|
93
|
precedence MUST be determined by comparing each dot separated identifier as
|
|
94
|
follows: identifiers consisting of only digits are compared numerically and
|
|
95
|
identifiers with letters or dashes are compared lexically in ASCII sort order.
|
|
96
|
Numeric identifiers always have lower precedence than non-numeric identifiers.
|
|
97
|
Example: 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-beta.2 < 1.0.0-beta.11 <
|
|
98
|
1.0.0-rc.1 < 1.0.0-rc.1+build.1 < 1.0.0 < 1.0.0+0.3.7 < 1.3.7+build <
|
|
99
|
1.3.7+build.2.b8f12d7 < 1.3.7+build.11.e0f985a.</p></li>
|
|
100
|
</ol>
|
|
101
|
|
|
102
|
|
|
103
|
<h2>Why Use Semantic Versioning?</h2>
|
|
104
|
|
|
105
|
<p>This is not a new or revolutionary idea. In fact, you probably do something
|
|
106
|
close to this already. The problem is that "close" isn't good enough. Without
|
|
107
|
compliance to some sort of formal specification, version numbers are
|
|
108
|
essentially useless for dependency management. By giving a name and clear
|
|
109
|
definition to the above ideas, it becomes easy to communicate your intentions
|
|
110
|
to the users of your software. Once these intentions are clear, flexible (but
|
|
111
|
not too flexible) dependency specifications can finally be made.</p>
|
|
112
|
|
|
113
|
<p>A simple example will demonstrate how Semantic Versioning can make dependency
|
|
114
|
hell a thing of the past. Consider a library called "Firetruck." It requires a
|
|
115
|
Semantically Versioned package named "Ladder." At the time that Firetruck is
|
|
116
|
created, Ladder is at version 3.1.0. Since Firetruck uses some functionality
|
|
117
|
that was first introduced in 3.1.0, you can safely specify the Ladder
|
|
118
|
dependency as greater than or equal to 3.1.0 but less than 4.0.0. Now, when
|
|
119
|
Ladder version 3.1.1 and 3.2.0 become available, you can release them to your
|
|
120
|
package management system and know that they will be compatible with existing
|
|
121
|
dependent software.</p>
|
|
122
|
|
|
123
|
<p>As a responsible developer you will, of course, want to verify that any
|
|
124
|
package upgrades function as advertised. The real world is a messy place;
|
|
125
|
there's nothing we can do about that but be vigilant. What you can do is let
|
|
126
|
Semantic Versioning provide you with a sane way to release and upgrade
|
|
127
|
packages without having to roll new versions of dependent packages, saving you
|
|
128
|
time and hassle.</p>
|
|
129
|
|
|
130
|
<p>If all of this sounds desirable, all you need to do to start using Semantic
|
|
131
|
Versioning is to declare that you are doing so and then follow the rules. Link
|
|
132
|
to this website from your README so others know the rules and can benefit from
|
|
133
|
them.</p>
|
|
134
|
|
|
135
|
<h2>FAQ</h2>
|
|
136
|
|
|
137
|
<h3>How should I deal with revisions in the 0.y.z initial development phase?</h3>
|
|
138
|
|
|
139
|
<p>The simplest thing to do is start your initial development release at 0.1.0
|
|
140
|
and then increment the minor version for each subsequent release.</p>
|
|
141
|
|
|
142
|
<h3>How do I know when to release 1.0.0?</h3>
|
|
143
|
|
|
144
|
<p>If your software is being used in production, it should probably already be
|
|
145
|
1.0.0. If you have a stable API on which users have come to depend, you should
|
|
146
|
be 1.0.0. If you're worrying a lot about backwards compatibility, you should
|
|
147
|
probably already be 1.0.0.</p>
|
|
148
|
|
|
149
|
<h3>Doesn't this discourage rapid development and fast iteration?</h3>
|
|
150
|
|
|
151
|
<p>Major version zero is all about rapid development. If you're changing the API
|
|
152
|
every day you should either still be in version 0.x.x or on a separate
|
|
153
|
development branch working on the next major version.</p>
|
|
154
|
|
|
155
|
<h3>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?</h3>
|
|
156
|
|
|
157
|
<p>This is a question of responsible development and foresight. Incompatible
|
|
158
|
changes should not be introduced lightly to software that has a lot of
|
|
159
|
dependent code. The cost that must be incurred to upgrade can be significant.
|
|
160
|
Having to bump major versions to release incompatible changes means you'll
|
|
161
|
think through the impact of your changes, and evaluate the cost/benefit ratio
|
|
162
|
involved.</p>
|
|
163
|
|
|
164
|
<h3>Documenting the entire public API is too much work!</h3>
|
|
165
|
|
|
166
|
<p>It is your responsibility as a professional developer to properly document
|
|
167
|
software that is intended for use by others. Managing software complexity is a
|
|
168
|
hugely important part of keeping a project efficient, and that's hard to do if
|
|
169
|
nobody knows how to use your software, or what methods are safe to call. In
|
|
170
|
the long run, Semantic Versioning, and the insistence on a well defined public
|
|
171
|
API can keep everyone and everything running smoothly.</p>
|
|
172
|
|
|
173
|
<h3>What do I do if I accidentally release a backwards incompatible change as a minor version?</h3>
|
|
174
|
|
|
175
|
<p>As soon as you realize that you've broken the Semantic Versioning spec, fix
|
|
176
|
the problem and release a new minor version that corrects the problem and
|
|
177
|
restores backwards compatibility. Remember, it is unacceptable to modify
|
|
178
|
versioned releases, even under this circumstance. If it's appropriate,
|
|
179
|
document the offending version and inform your users of the problem so that
|
|
180
|
they are aware of the offending version.</p>
|
|
181
|
|
|
182
|
<h3>What should I do if I update my own dependencies without changing the public API?</h3>
|
|
183
|
|
|
184
|
<p>That would be considered compatible since it does not affect the public API.
|
|
185
|
Software that explicitly depends on the same dependencies as your package
|
|
186
|
should have their own dependency specifications and the author will notice any
|
|
187
|
conflicts. Determining whether the change is a patch level or minor level
|
|
188
|
modification depends on whether you updated your dependencies in order to fix
|
|
189
|
a bug or introduce new functionality. I would usually expect additional code
|
|
190
|
for the latter instance, in which case it's obviously a minor level increment.</p>
|
|
191
|
|
|
192
|
<h3>What should I do if the bug that is being fixed returns the code to being compliant with the public API (i.e. the code was incorrectly out of sync with the public API documentation)?</h3>
|
|
193
|
|
|
194
|
<p>Use your best judgment. If you have a huge audience that will be drastically
|
|
195
|
impacted by changing the behavior back to what the public API intended, then
|
|
196
|
it may be best to perform a major version release, even though the fix could
|
|
197
|
strictly be considered a patch release. Remember, Semantic Versioning is all
|
|
198
|
about conveying meaning by how the version number changes. If these changes
|
|
199
|
are important to your users, use the version number to inform them.</p>
|
|
200
|
|
|
201
|
<h3>How should I handle deprecating functionality?</h3>
|
|
202
|
|
|
203
|
<p>Deprecating existing functionality is a normal part of software development and is often required to make forward progress. When you deprecate part of your public API, you should do two things: (1) update your documentation to let users know about the change, (2) issue a new minor release with the deprecation in place. 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 API.</p>
|
|
204
|
|
|
205
|
<h2>About</h2>
|
|
206
|
|
|
207
|
<p>The Semantic Versioning specification is authored by <a href="http://tom.preston-werner.com">Tom Preston-Werner</a>, inventor of Gravatars and cofounder of GitHub.</p>
|
|
208
|
|
|
209
|
<p>If you'd like to leave feedback, please <a href="https://github.com/mojombo/semver/issues">open an issue on GitHub</a>.</p>
|
|
210
|
|
|
211
|
<h2>License</h2>
|
|
212
|
|
|
213
|
<p>Creative Commons - CC BY 3.0
|
|
214
|
http://creativecommons.org/licenses/by/3.0/</p>
|
|
215
|
|
|
216
|
</body>
|
|
217
|
</html>
|