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 ¶
const ( // 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}" )
const Filename = ".colophon.yaml"
Filename is the manifest's fixed name on the release branch.
Variables ¶
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") )
var ErrBadComponent = errors.New("bad component")
ErrBadComponent reports a `components` entry the schema refuses. Spec 0010 D1.
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 TagName ¶ added in v0.5.0
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
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.
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 ¶
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 (Manifest) OwnComponents ¶ added in v0.5.0
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.