Documentation
¶
Overview ¶
Package notes collects the prose a commit contributes to its release's notes.
Generated release notes are a list of subject lines, and a subject line is a summary. The thing a reader most needs — this config format changed, edit the file before upgrading — is usually written in the commit body by the person who knew it. Nothing looks there.
Why the commit and not the merge request ¶
releaser-pleaser reads this from a merge request description. Colophon cannot, and the reason is mechanical rather than a matter of taste.
Every project in this estate merges fast-forward with squash off by default, and under those settings a merge request's description is not in the git history at all. Reading one means asking the forge to map a commit back to its merge request: an API call per commit, unavailable on Bitbucket without a human-installed app, broken for cherry-picked commits, and impossible in a repository read without credentials — which `plan` is specifically designed to be.
It would also make the notes depend on whether whoever merged happened to squash. Squashing is a judgement about whether a branch's commits carry historical value; it is not a precondition for release notes (spec 0001 D5a).
See spec 0003.
Index ¶
Constants ¶
const DefaultHeading = "Notes"
DefaultHeading reads correctly in either position.
const FenceInfo = "release-note"
FenceInfo is the info string that opens a fenced note block.
const Trailer = "release-note"
Trailer is the git trailer a commit uses for a short note.
Variables ¶
This section is empty.
Functions ¶
func Extract ¶
Extract returns the notes a single commit message carries, in the order they appear in the message.
On that order ¶
Blocks always precede trailers, and this is a property rather than a choice. A trailer is only a trailer when it sits in the message's LAST paragraph, so a fenced block appearing after one would stop it being a trailer at all. There is therefore no message in which a trailer precedes a block.
Types ¶
type Commit ¶
Commit is the minimum Collect needs. It is not policy.Commit: notes has no opinion about versions, and a package that only reads prose should not depend on the one that decides releases.
type Placement ¶
type Placement string
Placement says where the collected notes sit relative to the generated body.
const ( // Prepend puts the notes before the generated entries, which is the // default: these are most often upgrade or migration notes, and a warning // after the feature list is a warning read too late. Prepend Placement = "prepend" // Append puts them after, for a project that uses them as footnotes. Append Placement = "append" )