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