Documentation
¶
Overview ¶
Package scheme holds the version schemes colophon can release under.
A scheme owns three questions a version answers — what tag carries it, what the next one is, and how two of them order — so that the packages around it can hold a version without knowing which kind it is (spec 0016).
Index ¶
- Variables
- func For(v manifest.Versioning, read Reader) (policy.Scheme, error)
- type Ordinal
- func (Ordinal) Between(from, to policy.Version) policy.Bump
- func (Ordinal) Breaking(policy.Version) (policy.Bump, string)
- func (o Ordinal) First() policy.Version
- func (o Ordinal) Next(current policy.Version, b policy.Bump) (policy.Version, error)
- func (o Ordinal) Parse(raw string) (policy.Version, bool)
- func (Ordinal) Read(s string) (policy.Version, bool)
- func (Ordinal) Tag(v policy.Version) string
- type OrdinalVersion
- type Reader
- type Semver
- func (Semver) Between(from, to policy.Version) policy.Bump
- func (Semver) Breaking(current policy.Version) (policy.Bump, string)
- func (Semver) First() policy.Version
- func (Semver) Next(current policy.Version, b policy.Bump) (policy.Version, error)
- func (Semver) Parse(raw string) (policy.Version, bool)
- func (s Semver) Read(tag string) (policy.Version, bool)
- func (s Semver) Tag(v policy.Version) string
- type SemverVersion
Constants ¶
This section is empty.
Variables ¶
var ErrNoPrefix = errors.New("no version prefix")
ErrNoPrefix reports a prefix file that names no prefix.
var ErrPrefixMovedBack = errors.New("the version prefix moved backwards")
ErrPrefixMovedBack reports a configured prefix lower than the one the latest tag carries.
Functions ¶
Types ¶
type Ordinal ¶
type Ordinal struct {
// Prefix is what the NEXT release is built from, from the manifest. It may
// differ from the prefix of the latest tag, which is how a prefix moves.
Prefix string
}
Ordinal releases as a prefix and a build ordinal: n9.0.1-6, where the prefix names something outside this repository — for ffmpeg-wasi the upstream FFmpeg release it is built from — and the ordinal counts our builds of it.
The ordinal carries no meaning beyond order. It does not encode a break, a feature or a fix, and it restarts when the prefix moves, so it is comparable only within one prefix (spec 0016 D4).
func (Ordinal) Between ¶
Between reports a step, because that is all this scheme has: every release moves the ordinal by one and none of them moves it further.
func (Ordinal) Breaking ¶
Breaking reports a breaking change as a reason to release, and nothing more.
There is no major to cut here, which is accepted rather than worked around: the version says only which build this is, and a break is described in the release notes, where a person reads it.
func (Ordinal) Next ¶
Next increments the ordinal by one, whatever landed, and restarts at 1 when the prefix has moved (spec 0016 D4, D6).
func (Ordinal) Parse ¶
Parse reads a stated version, which for this scheme is written exactly as its tag: there is nothing to be generous or strict about.
type OrdinalVersion ¶
OrdinalVersion is one release of one prefix.
func (OrdinalVersion) Compare ¶
func (o OrdinalVersion) Compare(other policy.Version) int
Compare orders by prefix first and ordinal second.
The prefix is compared the way a person reads it, digit runs numerically and the rest as text, so n10.0.0 comes after n9.0.1 rather than between n1 and n2. history sorts every tag it finds to pick the current version, so a lexical comparison there would silently build the next release on the wrong one.
func (OrdinalVersion) String ¶
func (o OrdinalVersion) String() string
String is the version as it is written, which for this scheme is also the tag. An ordinal of zero is a project that has not released this prefix yet, and shows as the bare prefix rather than as a fictional -0.
type Reader ¶
Reader reads a file out of the repository the manifest came from, by a path relative to its root.
A function rather than a directory because the manifest is not always on disk: `publish` and `release --tag` read it out of the remote at a commit, and a prefix file has to come from the same place as the manifest that names it, or the two could describe different releases.
type Semver ¶
type Semver struct {
// TagPrefix is what a root tag carries before its version. Empty means
// "v"; a template such as rtb-error-v{version} sets "rtb-error-v"
// (spec 0027 D1).
TagPrefix string
}
Semver is the scheme every repository in the estate releases under: SemVer 2.0.0, tagged with a leading v unless the root names a template.
func (Semver) Between ¶
Between reports how far one version moved to reach another, which is what a Release-As: trailer's step is reported as.
func (Semver) Breaking ¶
Breaking holds a breaking change to a MINOR below 1.0.
releaser-pleaser promotes one unconditionally, so on a v0.x project a single `BREAKING CHANGE:` footer cuts v1.0.0 — an unintended stability promise, published and immutable. SemVer permits breaking changes in a minor below 1.0, so colophon takes that reading and reaching 1.0.0 stays something a maintainer chooses.
func (Semver) Next ¶
Next increments a version, keeping every rule the policy package held before this scheme existed.
func (Semver) Parse ¶
Parse reads a version a maintainer stated, STRICTLY.
Masterminds coerces: "1" becomes 1.0.0 and "01.00.00" becomes 1.0.0. A coerced Release-As: is a guess about which permanent tag to cut, so this refuses where Read would tolerate. The leading v is accepted deliberately — every tag in this estate carries one, so that is what a maintainer types.
func (Semver) Read ¶
Read parses a tag, as generously as Masterminds does: a leading v, and a partial version such as v1.2 coerced to 1.2.0.
A name containing "/" belongs to a directory, never to the root, whatever follows the slash (spec 0007 D8).
Under a template only a tag carrying its prefix is the root's, so an old v-tag a repository carries from before the template is not read as a release.
type SemverVersion ¶
type SemverVersion struct {
// contains filtered or unexported fields
}
SemverVersion is a semantic version behind policy.Version.
func (SemverVersion) Compare ¶
func (s SemverVersion) Compare(other policy.Version) int
Compare orders two semantic versions by SemVer precedence. A version of another scheme orders below any of this one, which cannot arise from a single repository and is answered rather than panicked on.
func (SemverVersion) String ¶
func (s SemverVersion) String() string