changelog¶

changelog walks a repository's Conventional Commits to generate a categorised changelog, hands the same commits back as a typed list, and parses an existing release-notes document into Changelog → Release → Entry you can query.

go get gitlab.com/phpboyscout/go/changelog

// Generate from the repo's tags and commits.
md, err := changelog.GenerateFromRepo(".", changelog.WithSinceTag("v1.2.0"))

// Parse existing notes and inspect them.
cl, err := changelog.Parse(rawNotes) // ErrNoReleases when nothing parseable
if cl.HasBreakingChanges() {
    // ...
}

It is a library, not a command: there is no binary, no configuration file and no environment variable. Everything that varies is an argument.

Start here¶

Generate your first changelog takes fifteen minutes, from an empty directory to a CHANGELOG.md and a build that fails on a breaking change.

Three ways in¶

Generate from git history. GenerateFromRepo opens the repo with go-git, reads tags and commits, classifies each Conventional Commit, and renders newest-first markdown. Bound it with WithSinceTag or WithMaxReleases, narrow it to a directory with WithPaths, and keep non-conforming commit messages with WithIncludeAll.
Read commits. CommitsFromRepo walks the same history with the same options and returns []Commit, hash and body included, for a program that decides something from the commits instead of printing them. It keeps the test and ci commits the generator drops.
Parse existing release notes. Parse and ParseFromArchive turn a markdown changelog (or a gzip/tar release archive) back into a typed Changelog. HasBreakingChanges, BreakingChanges and EntriesByCategory query it, and FormatSummary renders a short summary.

How commits become entries¶

Each commit subject is classified into a Category (breaking, feature, fix, performance or other) with its scope and description pulled out, and attributed to the earliest release whose tag can reach it. Releases are ordered by semver, newest first.

Commit classification says which types map where, and which are dropped.
How commits are attributed to releases explains why ancestry beats dates, and what happens to merge commits and re-tags.

Look something up¶

The reference section covers every option and its default, the exact markdown emitted, the exact markdown accepted, and every error value. Go signatures live on pkg.go.dev.

Before designing around it, read what changelog does not do: no CLI, no templating, no commit links, no scope filtering, and nothing in a generated changelog that came from a commit body except the breaking-change flag.

No framework weight¶

The direct dependencies are go-git, the leodido conventional-commits parser, x/mod and go/errors. A depfootprint test keeps go-tool-base, the CLI and TUI stacks, OpenTelemetry and the cloud SDKs out of the graph.