forked from simversion/simversion.github.io
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathindex.html
149 lines (104 loc) · 6.78 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>SimVersion</title>
<meta name="description" content="A simple, pragmatic versioning convention. A simple alternative to SemVer.">
<link href='https://fonts.googleapis.com/css?family=Pacifico' rel='stylesheet' type='text/css'>
<link rel="stylesheet" href="style.css">
</head>
<body>
<header class="wrapper-large ta-center">
<h1>SimVersion</h1>
<p>A simple, pragmatic versioning convention.</p>
<h4>(November 22, 2016)</h4>
</header>
<section class="wrapper"><article>
<p>This document describes a convention for versioning, under source-control, with package managers.</p>
<h2><a name="series" aria-hidden="true"></a>Series</h2>
<p>An API has two series of releases: feature-complete, and feature-incomplete.</p>
<h3><a name="feature-incomplete" aria-hidden="true"></a>Feature-incomplete</h3>
<p>Feature-incomplete releases use a version numbering scheme <code>0.MAJOR.UPDATE</code>, where:</p>
<ul>
<li><code>0</code> indicates a feature-incomplete release</li>
<li><code>MAJOR</code> increases for releases with <em>breaking</em> changes</li>
<li><code>UPDATE</code> increases for releases with <em>compatible</em> changes</li>
</ul>
<p>Increase of the <code>MAJOR</code> version number indicates backwards-incompatible API changes.</p>
<p>Increase of the <code>UPDATE</code> number indicates any other minor change, e.g. bugfixes, new compatible features, documentation updates, etc.</p>
<p>Example:</p>
<ul>
<li><code>0.1.0</code> is the initial, incomplete release</li>
<li><code>0.1.1</code> is the next compatible, still-incomplete release</li>
<li><code>0.2.0</code> is the next incompatible, still-incomplete release</li>
</ul>
<p>Note that, because the <code>0.x</code> series is by definition feature-incomplete, the addition of new features is expected, and
therefore is not indicated any differently from any other change.</p>
<h3><a name="feature-complete" aria-hidden="true"></a>Feature-complete</h3>
<p>The first feature-complete release is indicated by the release of version <code>1.0.0</code>.</p>
<p>Feature-complete releases use a version numbering scheme <code>MAJOR.MINOR.PATCH</code>, where:</p>
<ul>
<li><code>MAJOR</code> increases for releases with <em>breaking</em> changes</li>
<li><code>MINOR</code> increases for releases introducing <em>new features</em></li>
<li><code>PATCH</code> increases for releases with <em>compatible</em> changes</li>
</ul>
<p>Increase of the <code>MAJOR</code> version number indicates backwards-incompatible API changes.</p>
<p>Increase of the <code>MINOR</code> version number indicates compatible API changes introducing <em>new features</em>.</p>
<p>Increase of the <code>PATCH</code> number indicates any other minor change, e.g. bugfixes, documentation updates, etc.</p>
<p>Example:</p>
<ul>
<li><code>1.0.0</code> is the first feature-complete release</li>
<li><code>1.0.1</code> is the next compatible release with minor changes or bugfixes</li>
<li><code>1.1.0</code> is the next compatible release introducing new features</li>
<li><code>2.0.0</code> is the next incompatible release with breaking changes</li>
</ul>
<h2><a name="guide" aria-hidden="true"></a>Guidelines</h2>
<p>Every release, whether or not it's feature-complete, is considered "stable", in the sense
that it's expected to work - in terms of source-control, an unstable release should <em>never</em>
be tagged, but may exist on a pre-release branch, until it's ready for release.</p>
<p>The <code>0.x</code> release series indicates that the API is still incomplete and doesn't yet include
or support all of the planned features. Increase the version number to <code>1.0.0</code> when the API
is feature-complete.</p>
<p><em>Always</em> increase the <code>MAJOR</code> version number for any breaking change, regardless of whether the
release is feature-complete or not.</p>
<p><em>Never</em> increase the <code>MAJOR</code> version number for backwards-compatible changes.</p>
<p>The initial <code>1.0.0</code> release <em>may</em> have breaking changes - your change log should indicate if it does.</p>
<p>Deprecation is a minor change. Removal is a breaking change.</p>
<p>Accidental release of a breaking change with a minor version number increase must be corrected
by an immediate minor release reverting the change, and a subsequent <code>MAJOR</code> release.</p>
<p>A major update to an external dependency imported by your package does not automatically lead
to a major version increase in your package - while it could lead to blockage (in a package
with a conflicting version constraint for the same external dependency) it doesn't always,
for example, if changes to an external dependency do <em>not</em> result in any breaking changes to
your public API.</p>
<p>Breaking changes to <em>internal</em> APIs with a minor version increase are permitted, for classes
(and other source elements) that have been <em>explicitly</em> marked as implementation details intended
for internal use only, e.g. with a formal annotation or doc-block.</p>
<hr/>
<h2><a name="semver" aria-hidden="true"></a>Relationship with SemVer</h2>
<p>In a sense, this is a subset of <a href="http://semver.org/">SemVer</a>, but with slightly different semantics.</p>
<p>This convention uses two distinct release series with slightly different semantics and scope,
which match the caret operator for version constraints, e.g. as implemented by package management
tools such as <a href="https://getcomposer.org/">Composer</a> and <a href="https://www.npmjs.com/">npm</a>.</p>
<p>Unlike SemVer, the feature-incomplete <code>0.x</code> series does <em>not</em> allow breaking changes from <code>0.1.0</code>
to <code>0.1.1</code> - in practice, this is generally how the caret <code>^</code> operator version constraint works
with most package managers, e.g. in <code>composer.json</code> with Composer and <code>package.json</code> with npm.</p>
<p>This convention does not permit the use of pre-release identifiers, as in <code>1.0.0-alpha</code>, etc. -
the notion of pre-releases is outside the scope of this convention, which recognizes that this
problem can solved in a number of ways, for example (typically) by treating e.g. a <code>1.0.0</code> <em>branch</em>
(under source-control) as a pre-release, and a <code>1.0.0</code> <em>tag</em> as a release.</p>
</article></section>
<footer class="grid wrapper">
<div class="copyright">
Author: <a href="https://github.com/mindplay" target="_blank">Rasmus Schultz</a>
</div>
<div class="ta-right">
<a href="https://spdx.org/licenses/MIT" target="_blank">MIT</a>
|
<a href="https://github.com/simversion/simversion.github.io" target="_blank">Fork it on GitHub</a>
</div>
</footer>
</body>
</html>