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 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") // 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") )
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
// 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
}
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.
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.