scheme

package
v0.21.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 19, 2026 License: MIT Imports: 11 Imported by: 0

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

Constants

This section is empty.

Variables

View Source
var ErrNoPrefix = errors.New("no version prefix")

ErrNoPrefix reports a prefix file that names no prefix.

View Source
var ErrPrefixMovedBack = errors.New("the version prefix moved backwards")

ErrPrefixMovedBack reports a configured prefix lower than the one the latest tag carries.

Functions

func For

func For(v manifest.Versioning, read Reader) (policy.Scheme, error)

For builds the scheme a manifest describes, reading the prefix file through read when it names one.

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

func (Ordinal) Between(from, to policy.Version) policy.Bump

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

func (Ordinal) Breaking(policy.Version) (policy.Bump, string)

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) First

func (o Ordinal) First() policy.Version

First is the configured prefix with no release yet against it.

func (Ordinal) Next

func (o Ordinal) Next(current policy.Version, b policy.Bump) (policy.Version, error)

Next increments the ordinal by one, whatever landed, and restarts at 1 when the prefix has moved (spec 0016 D4, D6).

func (Ordinal) Parse

func (o Ordinal) Parse(raw string) (policy.Version, bool)

Parse reads a stated version, which for this scheme is written exactly as its tag: there is nothing to be generous or strict about.

func (Ordinal) Read

func (Ordinal) Read(s string) (policy.Version, bool)

Read answers any <prefix>-<ordinal> tag, not only ones under the configured prefix: a repository whose upstream has just moved carries its latest release under the PREVIOUS prefix, and refusing to read it would make that repository look as though it had never released.

func (Ordinal) Tag

func (Ordinal) Tag(v policy.Version) string

Tag is the version itself: this scheme's versions are written as their tags, with no v and no decoration.

type OrdinalVersion

type OrdinalVersion struct {
	Prefix  string
	Ordinal int
}

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

type Reader func(path string) ([]byte, error)

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.

func FromDisk

func FromDisk(root string) Reader

FromDisk reads relative to a working-tree root, which is what `plan` and `propose` have.

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

func (Semver) Between(from, to policy.Version) policy.Bump

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

func (Semver) Breaking(current policy.Version) (policy.Bump, string)

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) First

func (Semver) First() policy.Version

First is where a project that has never released starts.

func (Semver) Next

func (Semver) Next(current policy.Version, b policy.Bump) (policy.Version, error)

Next increments a version, keeping every rule the policy package held before this scheme existed.

func (Semver) Parse

func (Semver) Parse(raw string) (policy.Version, bool)

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

func (s Semver) Read(tag string) (policy.Version, bool)

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.

func (Semver) Tag

func (s Semver) Tag(v policy.Version) string

Tag is the version behind the root's prefix: v unless a template says otherwise.

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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL