manifest

package
v0.7.0 Latest Latest
Warning

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

Go to latest
Published: Sep 7, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package manifest reads the optional file a maintainer commits to the release branch to hold a release back.

Why this file holds so little

An earlier design carried version overrides here too — an exact version, a bump floor, a prerelease marker. They were moved to a `Release-As:` commit trailer (see package policy), because the mechanism should match the LIFETIME of the thing it holds:

  • Promoting a project to 1.0.0 is a point-in-time event. Expressing it as a file means writing a marker, cutting the release, then remembering to remove the marker — and a stale one is a loaded gun. A commit trailer is attached to the change that motivates it, falls out of range on its own once the tag moves past it, and needs no cleanup.
  • Holding a release back is persistent. It stays true until somebody decides otherwise, so a file is exactly right: visible in the tree, removed by a commit, and obvious in a diff when it changes.

What both share, and why neither lives in the merge-request body: the forge contract notes that updating a body has an unsolvable lost-update race, and that which regions of a body are machine-owned is the CALLER's policy. Git already solved that problem for anything committed (spec 0001 D8).

Why go/yamldoc rather than a struct unmarshal

This file is a SAFETY control that a human writes and maintains, and it is read by a tool that cuts permanent tags. Three things follow, and a reflection-based unmarshal serves none of them well:

  • **Multiple documents are first-class.** A yaml.Decoder reads ONE document per call, so a hold written after a `---` separator was silently dropped and the release published. Here the count is simply visible.
  • **Unknown keys are refused with a message worth reading.** `holds: true` looks like a hold, and under a lenient decoder it parses cleanly and stops nothing. Naming the offending key beats a reflection error.
  • **gopkg.in/yaml.v3 is archived**, and rewrites merge keys, reflows folded scalars and escapes astral-plane characters. yamldoc is the toolkit's answer to that, already in this module's graph, and it is what colophon will need anyway the moment it edits a consumer's YAML rather than only reading its own.

Index

Constants

View Source
const (

	// VersionShared means the component's version is the root's: it is tagged
	// alongside the root release and has no changelog of its own.
	VersionShared = "shared"

	// VersionOwn means the component is decided, changelogged and tagged on
	// its own cadence, from the commits that touch it.
	VersionOwn = "own"

	// DefaultTagTemplate is Go's nested-module shape, the only one a
	// toolchain enforces (spec 0008 D3).
	DefaultTagTemplate = "{dir}/v{version}"
)
View Source
const Filename = ".colophon.yaml"

Filename is the manifest's fixed name on the release branch.

Variables

View Source
var (
	// ErrMultipleDocuments reports a manifest carrying more than one YAML
	// document. A hold in the second one would otherwise be invisible.
	ErrMultipleDocuments = errors.New("multiple YAML documents")

	// ErrUnknownField reports a key outside the schema — most usefully, a typo
	// of one that is in it.
	ErrUnknownField = errors.New("unknown field")

	// ErrNotABool reports a hold whose value is not plainly true or false.
	ErrNotABool = errors.New("not a boolean")

	// ErrUnknownPlacement reports a release-notes placement outside the
	// accepted set.
	ErrUnknownPlacement = errors.New("unknown placement")

	// ErrUnknownForge reports a forge name outside Forges.
	ErrUnknownForge = errors.New("unknown forge")

	// ErrForgeNotNameable reports a forge that exists but cannot be named for a
	// host of one's own: codeberg is codeberg.org, which is detected, and the
	// Bitbucket adapter pins api.bitbucket.org whatever the host.
	ErrForgeNotNameable = errors.New("forge cannot be named for another host")

	// ErrUnsupported reports a document yamldoc could parse but not decode.
	ErrUnsupported = errors.New("unsupported YAML")

	// ErrBadTagPath reports a tag_also entry that cannot become a tag: not a
	// list, not relative, a . or .. segment, listed twice, or a name git
	// refuses. Refused here, before anything is tagged, because tree.Tag
	// would refuse the same name later, after the root tag had been cut.
	ErrBadTagPath = errors.New("tag_also: not a directory colophon can tag")
)
View Source
var ErrBadComponent = errors.New("bad component")

ErrBadComponent reports a `components` entry the schema refuses. Spec 0010 D1.

View Source
var Forges = []string{"gitlab", "github", "gitea"}

Forges are the names a repository may give its forge: the adapters that honour a host of their own (spec 0009 D2).

Functions

func Dirs added in v0.5.0

func Dirs(components []Component) []string

Dirs lists the components' directories, in order.

func TagName added in v0.5.0

func TagName(template, dir, version string) string

TagName renders a component tag from its template. One function, so a per-component shape is a change in one place (spec 0008 constraint 1).

func ValidateForge added in v0.5.0

func ValidateForge(name string) (string, error)

ValidateForge normalises a forge name from the manifest or a flag and refuses one colophon cannot act on. Empty is accepted as "not named".

Types

type Component added in v0.5.0

type Component struct {
	Dir     string
	Version string

	// Tag is the template the component's tags follow: `{dir}`, `{name}` (the
	// last path element) and `{version}` (no `v`). Empty means
	// DefaultTagTemplate.
	Tag string

	Hold   bool
	Reason string
}

Component is a directory with a version of its own, or with the root's.

func (Component) TagName added in v0.5.0

func (c Component) TagName(version string) string

TagName renders the tag this component carries at a version.

type Manifest

type Manifest struct {
	// Hold stops `publish` acting on this release even once its merge request
	// has merged.
	//
	// It does NOT stop the version being computed or the release merge request
	// being maintained: a held release stays visible and reviewable, it simply
	// is not tagged. That is deliberate — a hold should make the pending
	// release easier to look at, not hide it.
	Hold bool

	// Reason is shown wherever the hold surfaces. A hold with no stated reason
	// is one nobody can safely lift.
	Reason string

	// ReleaseNotes shapes the section built from commits' Release-Note
	// annotations (spec 0003). Both fields are optional.
	ReleaseNotes ReleaseNotes

	// TagAlso names directories that receive their own tag alongside the
	// root's, `<dir>/<root tag>`, at the same commit (spec 0007). Colophon
	// reads nothing inside them.
	TagAlso []string

	// Components are the directories with a version of their own, or the
	// root's, in document order (spec 0010 D1).
	Components []Component

	// Forge names the forge for a remote whose host does not reveal it: a
	// self-hosted GitLab, a GitHub Enterprise Server or a Gitea instance
	// (spec 0009). One of Forges, or empty.
	Forge string
}

Manifest is persistent release state. Every field is optional; the zero value is the ordinary case, and most projects will never carry this file at all.

func Load

func Load(repoPath string) (Manifest, error)

Load reads the manifest from a repository, if it has one.

An absent file is the ordinary case and yields the zero Manifest: most projects never carry one. Only an unreadable or invalid file is an error — a manifest that cannot be understood must stop the run rather than be treated as "no hold", which is the whole reason this file is strict.

func Parse

func Parse(b []byte) (Manifest, error)

Parse reads a manifest. Empty or absent content yields the zero Manifest.

func (Manifest) IsZero

func (m Manifest) IsZero() bool

IsZero reports whether the maintainer stated nothing.

func (Manifest) OwnComponents added in v0.5.0

func (m Manifest) OwnComponents() []Component

OwnComponents are the components decided on their own cadence, in manifest order. A shared component is the root's business until the tag.

type ReleaseNotes

type ReleaseNotes struct {
	// Placement is "prepend" (the default) or "append".
	//
	// Prepend, because these are most often upgrade or migration notes and a
	// warning after the feature list is a warning read too late.
	Placement string

	// Heading titles the section. Empty means "Notes", which reads correctly in
	// either position.
	Heading string
}

ReleaseNotes is how a project places the notes its commits contributed.

Jump to

Keyboard shortcuts

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