render

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: 9 Imported by: 0

Documentation

Overview

Package render turns a decided release into the text a human reads: the changelog entry, and the body of the merge request proposing it.

Why colophon renders this rather than go/changelog

go/changelog emits no links, by charter: a link is forge-specific, needing a project URL, a host and a path convention that differ between forges, and adding them would mean either a template system or a forge dependency.

That charter is right, and the reason it cannot emit a link is exactly the reason colophon can — colophon knows which forge it is talking to, because it must talk to it anyway. The estate's changelogs are full of those links, so a project migrating to colophon should not get a file whose new entries look unlike its old ones (spec 0001).

Index

Constants

View Source
const DefaultHeading = "# Changelog"

DefaultHeading is the title a changelog file gets when colophon creates one.

Variables

View Source
var (
	// ErrNoReleases reports a changelog carrying no release section.
	ErrNoReleases = errors.New("changelog: no releases")

	// ErrUnreadableVersion reports a release heading colophon cannot read a
	// version out of.
	//
	// TopSection no longer RETURNS this: since colophon fails open, a heading it
	// cannot read a version from is skipped and reported in Section.Skipped
	// rather than being fatal. It remains the error versionFrom produces, and is
	// exported because a caller reading a single heading still needs to name it.
	ErrUnreadableVersion = errors.New("changelog: cannot read a version from the release heading")
)

Functions

func CategoryOf

func CategoryOf(commitType string, breaking bool) changelog.Category

CategoryOf maps a Conventional Commits type onto the changelog category it is listed under. Breaking outranks the type: a reader scanning for what will hurt should find it under Breaking Changes, not filed under Features.

func Changelog

func Changelog(r Release, links Links, settings notes.Settings) string

Changelog renders one release's section, in the shape this estate's repositories already carry.

A project migrating to colophon appends to a file that already has dozens of these; entries that looked different after the switch would make the file read as two documents.

func Insert

func Insert(existing, section string) string

Insert places section above the newest release already in existing, and returns the whole file.

Everything before the first release heading is a preamble and is preserved byte for byte. That matters because the preamble is not fixed across this estate: some projects carry two lines, others a paragraph explaining how the file is generated, and rewriting it would produce a diff on every release that has nothing to do with the release.

A "## " inside a fenced code block is not a release heading. Treating one as a heading would insert the new release inside somebody's example.

func TagVersion added in v0.5.0

func TagVersion(tag string, opts ...Option) (prefix, version string, ok bool)

TagVersion reads the version a tag ends with, as every tag colophon writes carries it: "v1.2.0" gives "1.2.0" with prefix "v", "lint/v0.7.0" gives "0.7.0" with prefix "lint/v". The prefix is what a component's template renders with an empty version (manifest.TagName), so the two compare directly. False when the tag ends in no version.

Types

type Entry

type Entry struct {
	Category changelog.Category
	Scope    string
	Subject  string
	SHA      string
}

Entry is one commit as the changelog shows it.

func EntriesFrom

func EntriesFrom(commits []policy.Commit) []Entry

EntriesFrom selects the commits that belong in a changelog section and maps them to entries.

What is included, and why it is not go/changelog's list

A commit appears if it CONTRIBUTED TO THE RELEASE — that is, if it moved the version — and not otherwise. That is feat, fix, perf and refactor, plus anything marked breaking regardless of type.

The estate's existing changelogs carry only Features and Bug Fixes, because releaser-pleaser releases only on feat and fix. Colophon deliberately releases on perf and refactor too, which creates a case that cannot arise under the old tool: a release whose only commit is a refactor. Excluding those types would render an empty section for it — a release that happened for no stated reason.

So the rule is derived from the policy rather than from a fixed list, and the two cannot drift: a type that stops moving the version stops appearing.

type Forge

type Forge string

Forge names a forge's URL conventions. It is the same string forge.Endpoint.Type registers under, so a caller that has one has the other.

const (
	GitLab    Forge = "gitlab"
	GitHub    Forge = "github"
	Gitea     Forge = "gitea"
	Codeberg  Forge = "codeberg"
	Bitbucket Forge = "bitbucket"
)

The forges colophon can render links for.

func (Forge) RequestRef added in v0.19.1

func (f Forge) RequestRef(number int) string

RequestRef is how the forge writes a merge or pull request's number in prose: !42 on GitLab, #42 everywhere else.

type Links struct {
	// Project is the project's web URL, without a trailing slash, e.g.
	// https://gitlab.com/phpboyscout/cicd
	Project string

	// Forge selects the path convention.
	Forge Forge
}

Links builds the web URLs a changelog entry carries.

The GitLab shapes are taken from what this estate's changelogs ACTUALLY contain, not from documentation. The rest follow each forge's documented convention and have not been seen in a rendered file here — they are marked as such in linkStyles, and the first project on one of those forges should check its first changelog rather than assume.

Where the forge is unknown or the project URL is empty, every method returns the empty string and the renderer omits the link rather than emitting a broken one. A changelog with no link is worse than one with links; a changelog with a link to nowhere is worse than both.

func (Links) Commit

func (l Links) Commit(sha string) string

Commit returns the URL for a commit, or "" when it cannot be built.

func (Links) Compare

func (l Links) Compare(from, to string) string

Compare returns the URL comparing two refs, or "" when it cannot be built.

Bitbucket's compare reads destination-first, which is why the arguments are swapped for it rather than the format string being written backwards — a reader of the table should not have to notice that one row means the opposite of the others.

func (Links) Release

func (l Links) Release(tag string) string

Release returns the URL for a release, or "" when it cannot be built.

The tag is escaped as one path segment: a component's tag carries a slash (`lint/v0.7.0`), and GitLab's release routes accept a tag only as a single segment, so `lint%2Fv0.7.0` is the one form that resolves there; GitHub serves either. Spec 0010 D6.

func (Links) Verified

func (l Links) Verified() bool

Verified reports whether this forge's paths have been confirmed against a real changelog in this estate. A caller may surface it; nothing here changes behaviour on it, because an unverified guess is still better than no link and the alternative is refusing to render for three forges out of five.

type Option added in v0.9.0

type Option func(*reading)

TopSection reads the newest release out of a changelog.

This is how `publish` learns which version landed. It reads the file at the commit that was merged rather than anything the forge holds, because under a fast-forward merge without a squash a merge request's body is not in git at all — see spec 0001 D5a — and because the file is what colophon itself wrote. Option narrows how a changelog is read.

func Under added in v0.9.0

func Under(s policy.Scheme) Option

Under names the version scheme the changelog's headings are written in. Absent, headings are read as semver, which is every repository in the estate but one (spec 0016).

type Release

type Release struct {
	// Version is the tag this release will carry, e.g. "v0.40.0".
	Version string

	// Previous is the tag before it, empty for a first release. Without one
	// there is nothing to compare against, so the compare link is omitted
	// rather than pointed at nothing.
	Previous string

	Entries []Entry
	Notes   []notes.Note
}

Release is everything a changelog section needs.

type Section

type Section struct {
	// Version is the release, without a leading "v".
	Version string

	// Tag is the release's tag as the heading wrote it: "v1.2.0" for the
	// root, "lint/v0.7.0" or "capabilitygen-v0.7.0" for a component (spec
	// 0010 D6). Version is always its tail.
	Tag string

	// Heading is the "## …" line the section opened with.
	Heading string

	// Body is the whole section, heading included.
	Body string

	// Skipped are the level-two headings passed over before the release was
	// found, in file order.
	//
	// They are RETURNED rather than logged because this package has no logger
	// and should not grow one: a pure function that reads a file is testable
	// without one. `publish` warns about each, so a changelog drifting away
	// from the shape colophon writes is visible in a job log rather than
	// silent.
	Skipped []string
}

Section is one release as the changelog records it.

func TopSection

func TopSection(content string, opts ...Option) (Section, error)

Jump to

Keyboard shortcuts

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