💾 Archived View for gmi.noulin.net › gitRepositories › version › file › README.md.gmi captured on 2023-07-10 at 14:38:18. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2023-01-29)
-=-=-=-=-=-=-
README.md (12097B)
1 RelVer:
2
3 - [Format](#format)
4 - [Summary](#summary)
5 - [Versioning](#versioning)
6 - [Range matching](#range-matching)
7 - [Advandced range Syntax](#advandced-range-syntax)
8
9 # Sheepy
10 This is a sheepy package for [sheepy](https://spartatek.se/r/sheepy/file/README.md.html) and using [libsheepy](https://spartatek.se/r/libsheepy/file/README.md.html)
11
12 # Usage
13
14 Install with spm: `spm install version`
15
16 Include header file:
17 - `#include "shpPackages/version/version.h"`
18
19 Usage examples are on the top of the headers and in `main.c`.
20
21
22 # Format
23
24 Release.Major.minor[.Patch[.Other...]][-prerelease][+build]
25
26 # Summary
27
28 Values in [] are optional, given a version number R.M.m.P.O, increment the:
29 1. Release version as you see fit.
30 2. Major version when you make incompatible API changes,
31 3. Minor version when you add functionality in a backwards-compatible manner, and
32 4. Patch version when you make backwards-compatible bug fixes.
33 5. Other version when you make internal changes, documentation update, non-visible change, ABI change, dependency updates.
34
35 The other optional labels are for pre-release and build metadata.
36
37 ## Based on semver 2.0.0
38
39 - Add release version on front of the major version
40 - All version components have a defined sorting order
41 - Arbitrary numbers of components
42 - The major version number has only one meaning: breaking change, major version 0 is a normal version (simplifies range criteria)
43 - Clear criteria for verion numbers, version strings and ordering
44 - Range and comparator syntax is specified
45 - Prereleases are supported in the comparators (include or exclude)
46
47 # Versioning
48
49 The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.
50
51 1. Versions MUST have the form Release.Major.minor (R.M.m), and MAY optionally have any number of additional components. All leading characters are ignored.
52 2. Other versions (R.M.m.P.O) MUST have a Patch version.
53 3. Missing components are equal to 0 or empty strings.
54 4. Numbers are digit strings composed of characters in [0-9] and MUST fit in a 64 bit int and MUST NOT contain leading zeroes. Numbers MUST increase numerically: For instance: 1.9.0 -> 1.10.0 -> 1.11.0.
55 5. Non numbers are strings composed of alphanumeric characters [a-zA-Z0-9].
56 6. Components are separated with dots, hyphen, plus sign and MAY be either numbers or strings and MUST NOT be empty.
57 7. Numbers preceded by a dot, a hyphen or a plus sign are sorted numerically.
58 8. Release version, Major version, minor version and Patch version MUST be numbers.
59 9. Components that are not numbers are sorted using lexicographic ordering.
60 10. Once a versioned package has been released, the contents of that version MUST NOT be modified. Any modifications MUST be released as a new version.
61 11. Release version 0 (0) is for initial development. Anything may change at any time. The public API should not be considered stable.
62 12. Version 1.0 defines the public API. The way in which the version number is incremented after this release is dependent on this public API and how it changes.
63 13. Release version R (R.M and R > 0) MUST NOT reset other components.
64 14. MAJOR version M (R.M and R > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API. It MAY include minor and patch level changes. Patch and minor version MUST be reset to 0 when major version is incremented.
65 15. Minor version m (R.M.m and R > 0) MUST be incremented if new, backwards compatible functionality is introduced to the public API. It MUST be incremented if any public API functionality is marked as deprecated. It MAY be incremented if substantial new functionality or improvements are introduced within the private code. It MAY include patch level changes. Patch version MUST be reset to 0 when minor version is incremented.
66 16. Patch version P (R.M.m.P and R > 0) MUST be incremented if only backwards compatible bug fixes are introduced. A bug fix is defined as an internal change that fixes incorrect behavior.
67 17. Other version O (R.M.m.P.O and R > 0) is a series of components with meanings as you see fit.
68 18. A pre-release version MAY be denoted by appending a hyphen and a series of components (1.0.0-2, 1.0.1-alpha.1). Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version.
69 19. Build metadata MAY be denoted by appending a plus sign and a series of components (1.0-2+b001, 1.0.1-alpha.1+archAmd64.3).
70 20. Precedence refers to how versions are compared to each other when ordered. Precedence MUST be calculated by separating the version into Release, Major, minor, Patch, Other and pre-release identifiers and build metadata in that order. Release version has the highest precedence and the most right component has the lowest.
71
72
73 ## How do I know when to release 1.0.0?
74
75 If your software is being used in production, it should probably already be 1.0.0. If you have a stable API on which users have come to depend, you should be 1.0.0. If you’re worrying a lot about backwards compatibility, you should probably already be 1.0.0.
76
77 ## How to comunicate a major change in the API?
78
79 Bump the release version and the Major version.
80
81
82 ## Doesn’t this discourage rapid development and fast iteration?
83
84 Release version zero is all about rapid development. If you’re changing the API every day you should either still be in version 0.y.z or on a separate development branch working on the next major version.
85
86
87 ## What do I do if I accidentally release a backwards incompatible change as a minor version?
88
89 As soon as you realize that you’ve broken the Versioning spec, fix the problem and release a new minor version that corrects the problem and restores backwards compatibility. Even under this circumstance, it is unacceptable to modify versioned releases. If it’s appropriate, document the offending version and inform your users of the problem so that they are aware of the offending version.
90
91
92
93 ## What should I do if I update my own dependencies without changing the public API?
94
95 That would be considered compatible since it does not affect the public API. Software that explicitly depends on the same dependencies as your package should have their own dependency specifications and the author will notice any conflicts. Determining whether the change is a Patch level or minor level modification depends on whether you updated your dependencies in order to fix a bug or introduce new functionality. I would usually expect additional code for the latter instance, in which case it’s obviously a minor level increment.
96
97
98 # Range matching
99
100 - Numbers are compared numerically
101 - Strings are compared using lexicographic ordering
102 - Numbers are compared to strings using lexicographic ordering
103
104
105 A comparator is composed of an operator and a version. The set of primitive operators is:
106
107 - < Less than
108 - <= Less than or equal to
109 - > Greater than
110 - >= Greater than or equal to
111 - = Equal. If no operator is specified, then equality is assumed, so this operator is optional, but MAY be included.
112 - Adding '-' to the version in a comparator selects the highest prerelease for the specified version
113 - Adding '+' to the version in a comparator selects the lowest build for the specified version
114
115 For example,
116 - the comparator >=1.2.7 would match the versions 1.2.7, 1.2.8, 2.5.3, and 1.3.9, but not the versions 1.2.6 or 1.1.0
117 - the comparator >1.2.7- would match 1.2.7 and 1.2.7-alpha.1
118 - the comparator >=1.2.7+ would match 1.2.7+arch64.build-1 and 1.2.7 but not and 1.2.7-alpha.1
119
120 Comparators can be joined by whitespace to form a comparator set, which is satisfied by the intersection of all of the comparators it includes.
121 A range is composed of one or more comparator sets, joined by ||. A version matches a range if and only if every comparator in at least one of the ||-separated comparator sets is satisfied by the version.
122 For example, the range >=1.2.7 <1.3.0 would match the versions 1.2.7, 1.2.8, and 1.2.99, but not the versions 1.2.6, 1.3.0, or 1.1.0.
123 The range 1.2.7 || >=1.2.9 <2.0.0 would match the versions 1.2.7, 1.2.9, and 1.4.6, but not the versions 1.2.8 or 2.0.0.
124
125 # Advandced range Syntax
126
127 ## Any version x.0.1 X.0.X 1.1.*.0
128
129 x,X,* select any value in component in comparators and ranges.
130
131 - * := >= 0.0.0 (Any version)
132 - x.1.2 := =0.1.2 || =1.1.2 || 2.1.2... (Any release version with specified major.minor)
133 - 1.0.0.x.2 := 1.0.0.0.2 || 1.0.0.1.2 || 1.0.0.2.2... (Any patch version with Release.Major.minor equal to 1.0.0 and with other version equal to 2)
134
135 ## Hyphen Ranges X.Y.Z - A.B.C
136
137 Specifies an inclusive set.
138
139 - 1.2.3 - 2.3.4 := >=1.2.3 <=2.3.4
140
141 If a partial version is provided as the first version in the inclusive range, then the missing pieces are replaced with zeroes.
142
143 - 1.2 - 2.3.4 := >=1.2.0 <=2.3.4
144
145 If a partial version is provided as the second version in the inclusive range, then all versions that start with the supplied parts of the tuple are accepted, but nothing that would be greater than the provided tuple parts.
146
147 - 1.2.3 - 2.3 := >=1.2.3 <2.4.0
148 - 1.2.3 - 2 := >=1.2.3 <3.0.0
149
150 ## X-Ranges 1.2.x 1.X 1.2.* *
151
152 Any of X, x or * may be used to "stand in" for any component.
153
154 - * := >=0.0.0 (Any version satisfies)
155 - 1.x := >=1.0.0- <2.0.0 (Matching major version)
156 - 1.2.x := >=1.2.0- <1.3.0 (Matching major and minor versions)
157 - 1.*- := >=1.0.0 <2.0.0 (Matching major version and prereleases)
158 - 1.X+ := >=1.0.0+ <2.0.0 (Matching major version and build version)
159
160
161 - "" (empty string) := * := >=0.0.0
162
163 ## Tilde Ranges ~1.1.2.3 ~1.2.3 ~1.2 ~1
164
165 Allows patch-level changes if a minor version is specified on the comparator. Allows minor-level changes if not.
166
167 - ~1.1.2.3 := >=1.1.2.3- <1.1.3.0
168 - ~1.1.2.3- := >=1.1.2.3 <1.1.3.0 (same as the line above, adds 1.1.2.3 prereleases)
169 - ~1.1.2 := >=1.1.2.0- <1.1.3.0 (Same as 1.1.2.x)
170 - ~1.1 := >=1.1.0.0- <1.2.0.0 (Same as 1.1.x)
171 - ~1 := >=1.0.0- <2.0.0 (Same as 1.x)
172 - ~0.2.3 >=0.2.3- <0.3.0
173 - ~0.2 := >=0.2.0- <0.3.0 (Same as 0.2.x)
174 - ~0 := >=0.0.0- <1.0.0 (same as 0.x)
175 - ~0- := >=0.0.0 <1.0.0 (same as 0.x-, same as the line above, adds 0.0.0 prereleases)
176 - ~1.2.3-beta.2 := >=1.2.3-beta.2 <1.3.0 Note that prereleases in the 1.2.3 version will be allowed, if they are greater than or equal to beta.2. So, 1.2.3-beta.4 would be allowed, but 1.2.4-beta.2 would not, because it is a prerelease
177 of a different [major, minor, patch] tuple.
178
179 The any operator is allowed:
180
181 TODO - ~x.1.2.3 := >=0.1.2.3- < 0.1.3.0 || >=1.1.2.3- <1.1.3.0 || >=2.1.2.3- <2.1.3.0 ...
182
183 ## Caret Ranges ^1.2.3 ^0.2.5 ^0.0.4
184
185 Allows changes that do not modify the 2 left-most non-zero digits in the [release, major, minor, patch] tuple. In other words, this allows patch and minor updates.
186
187 - ^1.1.2.3 := >=1.1.2.3- <1.2.0.0
188 - ^0.0.2.3 := >=0.0.2.3- <0.1.0.0
189 - ^0.0.0.3 := >=0.0.0.3- <0.1.0.0
190 - ^1.2.3-beta.2 := >=1.2.3-beta.2 <1.3.0 Note that prereleases in the 1.2.3 version will be allowed, if they are greater than or equal to beta.2. So, 1.2.3-beta.4 would be allowed, but 1.2.4-beta.2 would not, because it is a prerelease
191 of a different [major, minor, patch] tuple.
192 - ^0.0.3-beta := >=0.0.3-beta <0.1.0 Note that prereleases in the 0.0.3 version only will be allowed, if they are greater than or equal to beta. So, 0.0.3-pr.2 would be allowed.
193
194 When parsing caret ranges, a missing patch value desugars to the number 0, but will allow flexibility within that value, even if the major and minor versions are both 0.
195
196 - ^1.1.2.x := >=1.1.2.0- <1.2.0.0
197 - ^0.0.0.x := >=0.0.0- <0.1.0
198 - ^0.0 := >=0.0.0- <0.1.0
199
200 A missing minor and patch values will desugar to zero, but also allow flexibility within those values, even if the major version is zero.
201
202 - ^1.1.x := >=1.1.0- <1.2.0
203 - ^0.0.x := >=0.0.0- <0.1.0
204
205 The any operator is allowed:
206
207 TODO - ^#.1 := >=0.1.0- < 0.2.0 || >=1.1.0- <1.2.0 || >=2.1.0- <2.2.0 ...
208