notes

package
v0.21.4 Latest Latest
Warning

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

Go to latest
Published: Nov 19, 2026 License: MIT Imports: 2 Imported by: 0

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

View Source
const DefaultHeading = "Notes"

DefaultHeading reads correctly in either position.

View Source
const FenceInfo = "release-note"

FenceInfo is the info string that opens a fenced note block.

View Source
const Trailer = "release-note"

Trailer is the git trailer a commit uses for a short note.

Variables

This section is empty.

Functions

func Extract

func Extract(message string) []string

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.

func Render

func Render(body string, collected []Note, settings Settings) string

Render places the collected notes around a generated body.

The body is passed through untouched when there are no notes, so a project that never writes one sees exactly what it sees today.

Types

type Commit

type Commit struct {
	SHA  string
	Body string
}

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 Note

type Note struct {
	SHA  string
	Text string
}

Note is one annotation, with the commit that contributed it.

func Collect

func Collect(commits []Commit) []Note

Collect gathers every note across a range of commits, in the order the commits are given.

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"
)

type Settings

type Settings struct {
	Placement Placement
	Heading   string
}

Settings is how a project shapes its notes section.

Jump to

Keyboard shortcuts

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