manifest

package
v0.14.2 Latest Latest
Warning

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

Go to latest
Published: Sep 28, 2026 License: MIT Imports: 13 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 (
	// SchemeSemver is the default, and every repository in the estate but one.
	SchemeSemver = "semver"

	// SchemeOrdinal is a prefix and a build ordinal — n9.0.1-6 — for a project
	// versioned by something outside itself (spec 0016).
	SchemeOrdinal = "ordinal"
)

The schemes a manifest may name.

View Source
const (

	// AdapterFile is the name the file adapter is configured under.
	AdapterFile = "file"
)
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 (
	// ErrBadStanding reports a `standing` that is not a mapping of prefix and
	// suffix.
	ErrBadStanding = errors.New("standing is not a mapping")

	// ErrBadStandingPath reports a standing file that names something outside
	// the repository, or nothing at all.
	ErrBadStandingPath = errors.New("bad standing path")
)
View Source
var ErrBadAnnounce = errors.New("bad announce")

ErrBadAnnounce reports an `announce` block colophon cannot act on.

View Source
var ErrBadAsset = errors.New("bad asset")

ErrBadAsset reports an `assets` entry that does not name a file a release can carry.

View Source
var ErrBadComponent = errors.New("bad component")

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

View Source
var ErrBadVersioning = errors.New("bad versioning")

ErrBadVersioning reports a `versioning` block that does not describe a scheme colophon can release under.

View Source
var ErrSecretInManifest = errors.New("a secret belongs in the environment, not in the manifest")

ErrSecretInManifest reports a credential written into the manifest.

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 MissingStanding added in v0.11.0

func MissingStanding(m Manifest, exists func(path string) bool) []string

MissingStanding names the standing files this manifest names and exists does not find, as warnings ready to print.

It is shared by plan and propose so the warning arrives while the problem is still free to fix: a release cut without its standing text cannot be corrected without editing a published release, and D6 chose to warn rather than refuse. Spec 0021 D6.

func MissingStandingIn added in v0.11.0

func MissingStandingIn(root string, m Manifest) []string

MissingStandingIn is MissingStanding against a checkout on disk, which is what plan and propose have: both work from a working tree, not a remote.

func ParseHold added in v0.9.0

func ParseHold(field string, n yamldoc.Node) (bool, error)

ParseHold reads a hold value, which is the one rule both the root's `hold` and a component's answer to.

What is accepted, and in what order

The parser is asked first. `true`, `True`, `TRUE` and the false forms resolve as YAML 1.2 booleans and are read as such, which makes "is this a boolean" yamldoc's question rather than colophon's — the question colophon had no business answering, and answered with a table for one release.

`yes`, `no`, `on` and `off` are REFUSED, which surprises people and is worth saying why: YAML 1.2 removed them, so the parser reading this file types them as strings. Accepting them would mean colophon reading as true a value its own parser calls the string "yes".

Only where the parser says the node is a scalar of some OTHER type does Go's reading apply, and that is where `1`, `0`, `t`, `T`, `f` and `F` are accepted. They are a deliberate leniency for compatibility, kept because they have been accepted since the field existed and somebody will have written one.

The order is what makes the leniency safe: step two only ever sees values yamldoc has already typed as something else, so it can never disagree with the parser about a value the parser claimed. Spec 0015 D5, colophon#18.

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 Announce added in v0.11.0

type Announce struct {
	// Adapter is the name colophon knows it by — "discord" today.
	Adapter string

	// Webhook is an environment REFERENCE, "$NAME", never a value.
	Webhook string

	// When is the smallest release this adapter announces: "any", "patch",
	// "minor" or "major". Empty means any.
	When string

	// File is set only for the file adapter, whose settings are a repository
	// and a file rather than a webhook (spec 0023 D1).
	File *FileFeed
}

Announce is one adapter's configuration.

func AnnounceFromConfig added in v0.13.0

func AnnounceFromConfig(raw any) ([]Announce, error)

AnnounceFromConfig reads the operator's announce block, a plain value from the configuration layer, through the manifest's own parser so it is refused for the same reasons a manifest would be: a literal secret, an unknown field. A nil value is no block.

func ResolveAnnounce added in v0.13.0

func ResolveAnnounce(project, operator []Announce) ([]Announce, error)

ResolveAnnounce completes the project's announce block against the operator's (spec 0026 D2). Announcing is opt-in: only adapters the project names come back, each with the operator's settings underneath the project's own, then checked for completeness. An adapter only the operator names does nothing.

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

	// Standing is this component's own standing block, layered over the
	// root's by Resolve (spec 0021 D5). Zero means it inherits entirely.
	Standing Standing
}

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 Field added in v0.11.0

type Field struct {
	Key      string
	Template string
}

Field is one entry field, kept beside its position so the written order is the order the manifest lists (spec 0023 D4).

type FileFeed added in v0.11.0

type FileFeed struct {
	// Repo is the target, "owner/name". Branch is where the change lands,
	// empty meaning the repository's default.
	Repo   string
	Branch string

	// Token is an environment REFERENCE, "$NAME", never a value.
	Token string

	// Path is the file, templated. List names the sequence appended to, and
	// Key the entry field that decides whether this release is already there.
	Path string
	List string
	Key  string

	// Entry is appended; Header is written only when the file is created.
	// Both keep document order.
	Entry  []Field
	Header []Field

	// Message is the commit subject, templated.
	Message string

	// Format is "yaml" or "json". Empty means the path's extension decides,
	// and an extension nobody recognises is refused rather than assumed.
	Format string

	// StripPrefix is removed from the front of {path} and {path_dashed}.
	//
	// colophon knows a repository as its full forge path — "phpboyscout/go/config"
	// — and a record keyed by position within one group wants "go/config". The
	// group is not something colophon can infer, so the project names it.
	StripPrefix string

	Mode  Mode
	Merge Merge
}

FileFeed is the file adapter's configuration: a repository, a file, the list inside it, and the entry appended to that list.

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

	// Versioning says how this repository's versions are shaped. The zero
	// value is semver, which is what a manifest saying nothing means (spec
	// 0016).
	Versioning Versioning

	// Assets names the files a release carries, for a project whose artefacts
	// no build tool describes. Empty means colophon learns them from
	// goreleaser's manifest instead, which is every project in the estate but
	// one (spec 0017).
	Assets []string

	// Announce configures where a release is announced, in document order
	// (spec 0019).
	Announce []Announce
}

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 Merge added in v0.11.0

type Merge string

Merge is what the adapter asks the forge to do with the request it opened.

const (
	// MergeNever leaves the request for a person. The default.
	MergeNever Merge = ""

	// MergeWhenReady asks the forge to merge once its own checks pass.
	//
	// It is not "automerge": what is being asked is specifically that the
	// forge waits for its checks, and a forge that cannot wait is reported
	// rather than given a plain merge instead (spec 0023 D8).
	MergeWhenReady Merge = "when_ready"
)

type Mode added in v0.11.0

type Mode string

Mode is how the file adapter gets its change onto the target branch.

const (
	// ModeCommit commits to the branch and pushes. The default, because a
	// repository whose branch accepts a push wants the smallest thing that
	// works.
	ModeCommit Mode = "commit"

	// ModeMergeRequest pushes a branch and opens a merge request, for a
	// project that protects the branch the file lives on.
	ModeMergeRequest Mode = "merge_request"
)

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

	// Standing names the files carried on every release, wrapped around the
	// body. Placement and Heading place the notes section WITHIN that body and
	// are orthogonal to it (spec 0021 D2).
	Standing Standing
}

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

type Standing added in v0.11.0

type Standing struct {
	// Prefix is a repository-relative path, empty when none is named.
	Prefix string

	// Suffix is a repository-relative path, empty when none is named.
	Suffix string
}

Standing names the files a project carries on every release, wrapped around the generated body: the prefix before it and the suffix after it.

Two keys named by position rather than one key plus a placement value, so there is no placement to validate and a project can have both — which is the case that motivated it, where a licence choice belongs above the news and verification instructions below it. Spec 0021 D1.

func (Standing) Resolve added in v0.11.0

func (s Standing) Resolve(root Standing) Standing

Resolve layers a component's standing block over the root's, key by key, so a component may override the prefix and keep the root's suffix. Spec 0021 D5.

type Versioning added in v0.9.0

type Versioning struct {
	// Scheme is "semver" or "ordinal"; empty means semver.
	Scheme string

	// Prefix is the ordinal scheme's prefix, written in the manifest.
	Prefix string

	// PrefixFile names a file in the repository holding the prefix instead.
	// Exactly one of Prefix and PrefixFile is set under the ordinal scheme.
	PrefixFile string
}

Versioning says how this repository's versions are shaped. The zero value is semver, which is what a manifest that says nothing means.

func (Versioning) IsOrdinal added in v0.9.0

func (v Versioning) IsOrdinal() bool

IsOrdinal reports the ordinal scheme, which is the only non-default one.

Jump to

Keyboard shortcuts

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