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 semver.Version
Next semver.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 (Decision) Releasable ¶
Releasable reports whether anything should be released at all.