💾 Archived View for gmi.noulin.net › markdown › version_README.md captured on 2023-07-10 at 18:19:23.
-=-=-=-=-=-=-
RelVer:
- [Format](#format)
- [Summary](#summary)
- [Versioning](#versioning)
- [Range matching](#range-matching)
- [Advandced range Syntax](#advandced-range-syntax)
# Sheepy
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)
# Usage
Install with spm: `spm install version`
Include header file:
- `#include "shpPackages/version/version.h"`
Usage examples are on the top of the headers and in `main.c`.
# Format
Release.Major.minor[.Patch[.Other...]][-prerelease][+build]
# Summary
Values in [] are optional, given a version number R.M.m.P.O, increment the:
1. Release version as you see fit.
2. Major version when you make incompatible API changes,
3. Minor version when you add functionality in a backwards-compatible manner, and
4. Patch version when you make backwards-compatible bug fixes.
5. Other version when you make internal changes, documentation update, non-visible change, ABI change, dependency updates.
The other optional labels are for pre-release and build metadata.
## Based on semver 2.0.0
- Add release version on front of the major version
- All version components have a defined sorting order
- Arbitrary numbers of components
- The major version number has only one meaning: breaking change, major version 0 is a normal version (simplifies range criteria)
- Clear criteria for verion numbers, version strings and ordering
- Range and comparator syntax is specified
- Prereleases are supported in the comparators (include or exclude)
# Versioning
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.
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.
2. Other versions (R.M.m.P.O) MUST have a Patch version.
3. Missing components are equal to 0 or empty strings.
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.
5. Non numbers are strings composed of alphanumeric characters [a-zA-Z0-9].
6. Components are separated with dots, hyphen, plus sign and MAY be either numbers or strings and MUST NOT be empty.
7. Numbers preceded by a dot, a hyphen or a plus sign are sorted numerically.
8. Release version, Major version, minor version and Patch version MUST be numbers.
9. Components that are not numbers are sorted using lexicographic ordering.
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.
11. Release version 0 (0) is for initial development. Anything may change at any time. The public API should not be considered stable.
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.
13. Release version R (R.M and R > 0) MUST NOT reset other components.
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.
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.
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.
17. Other version O (R.M.m.P.O and R > 0) is a series of components with meanings as you see fit.
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.
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).
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.
## How do I know when to release 1.0.0?
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.
## How to comunicate a major change in the API?
Bump the release version and the Major version.
## Doesn’t this discourage rapid development and fast iteration?
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.
## What do I do if I accidentally release a backwards incompatible change as a minor version?
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.
## What should I do if I update my own dependencies without changing the public API?
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.
# Range matching
- Numbers are compared numerically
- Strings are compared using lexicographic ordering
- Numbers are compared to strings using lexicographic ordering
A comparator is composed of an operator and a version. The set of primitive operators is:
- < Less than
- <= Less than or equal to
- > Greater than
- >= Greater than or equal to
- = Equal. If no operator is specified, then equality is assumed, so this operator is optional, but MAY be included.
- Adding '-' to the version in a comparator selects the highest prerelease for the specified version
- Adding '+' to the version in a comparator selects the lowest build for the specified version
For example,
- 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
- the comparator >1.2.7- would match 1.2.7 and 1.2.7-alpha.1
- 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
Comparators can be joined by whitespace to form a comparator set, which is satisfied by the intersection of all of the comparators it includes.
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.
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.
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.
# Advandced range Syntax
## Any version x.0.1 X.0.X 1.1.*.0
x,X,* select any value in component in comparators and ranges.
- * := >= 0.0.0 (Any version)
- x.1.2 := =0.1.2 || =1.1.2 || 2.1.2... (Any release version with specified major.minor)
- 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)
## Hyphen Ranges X.Y.Z - A.B.C
Specifies an inclusive set.
- 1.2.3 - 2.3.4 := >=1.2.3 <=2.3.4
If a partial version is provided as the first version in the inclusive range, then the missing pieces are replaced with zeroes.
- 1.2 - 2.3.4 := >=1.2.0 <=2.3.4
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.
- 1.2.3 - 2.3 := >=1.2.3 <2.4.0
- 1.2.3 - 2 := >=1.2.3 <3.0.0
## X-Ranges 1.2.x 1.X 1.2.* *
Any of X, x or * may be used to "stand in" for any component.
- * := >=0.0.0 (Any version satisfies)
- 1.x := >=1.0.0- <2.0.0 (Matching major version)
- 1.2.x := >=1.2.0- <1.3.0 (Matching major and minor versions)
- 1.*- := >=1.0.0 <2.0.0 (Matching major version and prereleases)
- 1.X+ := >=1.0.0+ <2.0.0 (Matching major version and build version)
- "" (empty string) := * := >=0.0.0
## Tilde Ranges ~1.1.2.3 ~1.2.3 ~1.2 ~1
Allows patch-level changes if a minor version is specified on the comparator. Allows minor-level changes if not.
- ~1.1.2.3 := >=1.1.2.3- <1.1.3.0
- ~1.1.2.3- := >=1.1.2.3 <1.1.3.0 (same as the line above, adds 1.1.2.3 prereleases)
- ~1.1.2 := >=1.1.2.0- <1.1.3.0 (Same as 1.1.2.x)
- ~1.1 := >=1.1.0.0- <1.2.0.0 (Same as 1.1.x)
- ~1 := >=1.0.0- <2.0.0 (Same as 1.x)
- ~0.2.3 >=0.2.3- <0.3.0
- ~0.2 := >=0.2.0- <0.3.0 (Same as 0.2.x)
- ~0 := >=0.0.0- <1.0.0 (same as 0.x)
- ~0- := >=0.0.0 <1.0.0 (same as 0.x-, same as the line above, adds 0.0.0 prereleases)
- ~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
of a different [major, minor, patch] tuple.
The any operator is allowed:
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 ...
## Caret Ranges ^1.2.3 ^0.2.5 ^0.0.4
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.
- ^1.1.2.3 := >=1.1.2.3- <1.2.0.0
- ^0.0.2.3 := >=0.0.2.3- <0.1.0.0
- ^0.0.0.3 := >=0.0.0.3- <0.1.0.0
- ^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
of a different [major, minor, patch] tuple.
- ^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.
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.
- ^1.1.2.x := >=1.1.2.0- <1.2.0.0
- ^0.0.0.x := >=0.0.0- <0.1.0
- ^0.0 := >=0.0.0- <0.1.0
A missing minor and patch values will desugar to zero, but also allow flexibility within those values, even if the major version is zero.
- ^1.1.x := >=1.1.0- <1.2.0
- ^0.0.x := >=0.0.0- <0.1.0
The any operator is allowed:
TODO - ^#.1 := >=0.1.0- < 0.2.0 || >=1.1.0- <1.2.0 || >=2.1.0- <2.2.0 ...