policy

package
v0.5.0 Latest Latest
Warning

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

Go to latest
Published: Sep 5, 2026 License: MIT Imports: 7 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 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 Decide

func Decide(current semver.Version, commits []Commit) (Decision, error)

Decide computes the next version. It is total and pure.

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.

Jump to

Keyboard shortcuts

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