manifest

package
v0.3.0 Latest Latest
Warning

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

Go to latest
Published: Sep 3, 2026 License: MIT Imports: 8 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 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")

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

Functions

This section is empty.

Types

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
}

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.

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