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
- Variables
- func CategoryOf(commitType string, breaking bool) changelog.Category
- func Changelog(r Release, links Links, settings notes.Settings) string
- func Insert(existing, section string) string
- func TagVersion(tag string, opts ...Option) (prefix, version string, ok bool)
- type Entry
- type Forge
- type Links
- type Option
- type Release
- type Section
Constants ¶
const DefaultHeading = "# Changelog"
DefaultHeading is the title a changelog file gets when colophon creates one.
Variables ¶
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 ¶
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 ¶
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 ¶
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
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 ¶
Entry is one commit as the changelog shows it.
func EntriesFrom ¶
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
RequestRef is how the forge writes a merge or pull request's number in prose: !42 on GitLab, #42 everywhere else.
type Links ¶
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.
On how these paths are known ¶
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) Compare ¶
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 ¶
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 ¶
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.
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.