Documentation
¶
Overview ¶
Package policy decides what the next version is.
It is the most consequential thing colophon does and the easiest to get quietly wrong, so it is a PURE FUNCTION: no clock, no network, no filesystem, no git. Same inputs, same Decision, every time. Everything it needs arrives as an argument, which makes the whole of it exhaustively testable as a table and reviewable without running anything.
Where these rules come from ¶
Colophon computes its own bump rather than inheriting releaser-pleaser's, so spec 0001 D2 applies: parity is not a requirement, but divergence must be deliberate. Two divergences are, and both are recorded here rather than left for someone to discover from a diff.
Index ¶
Constants ¶
const ReleaseAsTrailer = "release-as"
ReleaseAsTrailer is the git trailer a maintainer uses to state the next version outright, e.g.
git commit --allow-empty -m "chore: release 1.0.0" -m "Release-As: 1.0.0"
The key is matched case-insensitively, following release-please, whose convention this deliberately borrows rather than inventing a colophon-only spelling.
Variables ¶
var ErrAmbiguousReleaseAs = errors.New("ambiguous Release-As trailers")
ErrAmbiguousReleaseAs reports two trailers that compare EQUAL under semver precedence but would produce different tags — "1.0.0+linux" and "1.0.0+darwin". Build metadata is ignored by precedence, so "highest wins" cannot separate them and commit order is not an answer: reversing the commits would change the permanent tag.
var ErrBadReleaseAs = errors.New("invalid Release-As trailer")
ErrBadReleaseAs reports a Release-As: trailer whose value is not a version. It is an error rather than a warning: a maintainer who wrote the trailer meant something by it, and guessing which version they meant is worse than refusing.
var ErrUnhandledBump = errors.New("unhandled bump")
ErrUnhandledBump reports a Bump value the incrementer does not know. It is unreachable via the exported API and exists so the switch is total.
var ErrVersionOverflow = errors.New("version increment overflows")
ErrVersionOverflow reports an increment that would wrap a version component past the maximum, producing a version LOWER than the current one.
Functions ¶
func Releases ¶
Releases reports whether a Conventional Commits type moves the version.
Exported so the changelog's inclusion rule can be derived from the release policy rather than restated beside it. A type that stops moving the version stops appearing in the changelog, without anyone having to remember to change two lists — and colophon's list is not the obvious one, because perf and refactor release here and do not under releaser-pleaser.
A breaking change moves the version whatever its type; that is the caller's check, not this one's, because it is a property of the commit rather than of the type.
Types ¶
type Commit ¶
type Commit struct {
SHA string
Type string // the Conventional Commits type: feat, fix, perf, ...
Scope string
Subject string
Breaking bool // from `!` or a BREAKING CHANGE: footer
// Body is the commit message below the subject. It is read only for
// trailers; policy does not otherwise care what is in it.
Body string
}
Commit is the minimum policy needs to reach a decision. It is deliberately not a git commit: policy never touches a repository.
type Decision ¶
type Decision struct {
Current Version
Next Version
Bump Bump
// Reasons holds only the commits that moved the version. A commit
// contributing BumpNone is not a reason for anything.
Reasons []Reason
// ReleaseAs records the version a `Release-As:` trailer asked for, when one
// was honoured. Empty when the commits alone decided it.
ReleaseAs string
// Notes explains any decision a reader would otherwise find surprising —
// a breaking change held to a minor below 1.0, an override applied, a
// floor raising the bump.
Notes []string
// contains filtered or unexported fields
}
Decision is the whole output.
func Decide ¶
Decide computes the next version. It is total and pure.
The scheme owns everything about the version itself — what the next one is, what a breaking change may do to it — so that this function holds only the Conventional Commits reading, which is the same under every scheme (spec 0016 D1).
func (Decision) Releasable ¶
Releasable reports whether anything should be released at all.
type Reason ¶
Reason records one commit's contribution, so `plan` can show its working and a maintainer can disagree with a specific commit rather than with a number.
type Scheme ¶ added in v0.9.0
type Scheme interface {
// Read answers whether a TAG names a version under this scheme, and
// which. A repository may carry tags this tool has no opinion about, so a
// name it does not recognise is skipped rather than refused.
Read(tag string) (Version, bool)
// Parse reads a version a maintainer STATED, as the value of a Release-As:
// trailer. Separate from Read because the two have different tolerances:
// a tag is read as generously as the scheme allows, and a stated version
// is read strictly, since it decides a permanent tag and a coerced answer
// would be a guess.
Parse(raw string) (Version, bool)
// Next is the version after current, given how far what landed moved it.
Next(current Version, b Bump) (Version, error)
// Tag is the tag that carries a version.
Tag(v Version) string
// First is where a project that has never released starts.
First() Version
// Between reports how far one version moved to reach another, which is
// how an honoured Release-As: trailer's step is reported.
Between(from, to Version) Bump
// Breaking says what a breaking change means at this version: how far it
// may move the version, and why, in the words `plan` shows.
//
// The one judgement in this package that is the scheme's rather than
// Conventional Commits': semver holds a break to a minor below 1.0 so a
// footer cannot cut 1.0.0 by accident, and a scheme with no major has
// nothing to hold it to.
Breaking(current Version) (Bump, string)
}
Scheme decides what a version is, what the next one is, and which tag carries it.
Declared here, where the decision it serves is made, and implemented in pkg/scheme. That direction keeps this package a pure function of its arguments with no knowledge of which schemes exist.
type Version ¶ added in v0.9.0
type Version interface {
String() string
// Compare orders two versions of the SAME scheme: negative when this one
// is lower, zero when equal, positive when higher.
Compare(other Version) int
}
Version is a released version under some scheme: what it is called, and how it orders against another.
An interface rather than a concrete type because a version is not always semver: ffmpeg-wasi releases n9.0.1-6, an upstream release and a build ordinal, which orders correctly among its own kind and not at all against anything else (spec 0016).