policy

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: 5 Imported by: 0

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

View Source
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

View Source
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.

View Source
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.

View Source
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.

View Source
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

func Releases(commitType string) bool

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 Bump

type Bump int

Bump is how far the version moves. Ordered, so the highest wins.

const (
	// BumpNone means nothing in the range warrants a release.
	BumpNone Bump = iota
	BumpPatch
	BumpMinor
	BumpMajor
)

func (Bump) String

func (b Bump) String() string

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

func Decide(s Scheme, current Version, commits []Commit) (Decision, error)

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

func (d Decision) Releasable() bool

Releasable reports whether anything should be released at all.

type Reason

type Reason struct {
	SHA     string
	Type    string
	Scope   string
	Subject string
	Bump    Bump
	Why     string
}

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

Jump to

Keyboard shortcuts

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