Skip to content

Getting started

This walks through both halves of changelog — generating one from a repository, and parsing one back into a queryable model.

Install

go get gitlab.com/phpboyscout/go/changelog

Go 1.26 or newer.

Generate a changelog from a repository

GenerateFromRepo takes a path to a git repository, reads its tags and Conventional-Commit history, and returns rendered markdown.

package main

import (
    "fmt"

    "gitlab.com/phpboyscout/go/changelog"
)

func main() {
    md, err := changelog.GenerateFromRepo(".")
    if err != nil {
        panic(err)
    }
    fmt.Println(md)
}

By default it includes releases since the second-most-recent tag. Shape it with options:

md, err := changelog.GenerateFromRepo(".",
    changelog.WithSinceTag("v1.2.0"), // only releases after this tag
    changelog.WithMaxReleases(5),     // cap the number of releases
)

// Everything, all releases:
md, err = changelog.GenerateFromRepo(".", changelog.WithIncludeAll())

See Generate from git history for the options in detail.

Parse an existing changelog

If you already have release notes (say, the CHANGELOG.md shipped in a release), parse it into a typed model and query it:

cl := changelog.Parse(rawNotes)

fmt.Println("from", cl.FromVersion, "to", cl.ToVersion)

if cl.HasBreakingChanges() {
    for _, e := range cl.BreakingChanges() {
        fmt.Printf("BREAKING %s: %s\n", e.Scope, e.Description)
    }
}

for _, e := range cl.EntriesByCategory(changelog.CategoryFeature) {
    fmt.Println("feature:", e.Description)
}

For a ready-made terminal summary:

fmt.Print(changelog.FormatSummary(cl))

Next steps