chglog

README

chglog

chglog is a changelog management library and tool

Why

While there are other tool out there that will create a changelog output as part of their workflow none of the ones I could find did so in a way that allowed formatting the output via multiple templates.

The need to multiple output formats was being driven by the desire to add changelog support to https://github.com/goreleaser/nfpm and the deb and rpm changelog formats not being the same.

Goals

• be simple to use
• provide decent default templates for deb, rpm, release and repository style changelog formats
• be distributed as a single binary
• reproducible results
  • depend on the fewer external things as possible
  • store changelog in a transportable format (.yml)
• be possible to use it as a lib in other go projects (namely goreleaser itself)

Install

go install github.com/goreleaser/chglog/cmd/chglog@latest

Usage

The first steps are to run chglog config to initialize a configuration file (.chglog.yml) and edit the generated file according to your needs:

conventional-commits: false
exclude-merge-commits: false
deb:
  distribution: []
  urgency: ""
debug: false
owner: ""
package-name: ""

The next step is to run chglog init.

- semver: 0.0.1
  date: 2019-10-18T16:05:33-07:00
  packager: dj gilcrease <example@example.com>
  changes:
    - commit: 2c499787328348f09ae1e8f03757c6483b9a938a
      note: |-
        oops i forgot to use Conventional Commits style message

        This should NOT break anything even if I am asking to build the changelog using Conventional Commits style message
    - commit: 3ec1e9a60d07cc060cee727c97ffc8aac5713943
      note: |-
        feat: added file two feature

        BREAKING CHANGE: this is a backwards incompatible change
    - commit: 2cc00abc77d401a541d18c26e5c7fbef1effd3ed
      note: |-
        feat: added the fileone feature

        * This is a test repo
        * so ya!

Then to generate a CHANGELOG.md file you would do chglog format --template repo > CHANGELOG.md

Now whenever you go to do another release you would do chglog add --version v#.#.# (version MUST be semver format)

And that's it!

Usage as lib

You can look at the code of chglog itself to see how to use it as a library

Status

• alpha

Donate

Donations are very much appreciated! You can donate/sponsor on the main goreleaser OpenCollective! It's easy and will surely help the developers at least buy some ☕️ or 🍺!

Stargazers over time

---

Would you like to fix something in the documentation? Feel free to open an issue.

Documentation

Overview

Package chglog contains the public API for working with a changlog.yml file

Index

• Variables
• func CommitsBetween(gitRepo *git.Repository, start, end plumbing.Hash, excludeMergeCommits bool) (commits []*object.Commit, err error)
• func DebTemplate() (*template.Template, error)
• func FormatChangelog(pkgLogs *PackageChangeLog, tpl *template.Template) (string, error)
• func GitHashFotTag(gitRepo *git.Repository, tagName string) (hash plumbing.Hash, err error)
• func GitRepo(gitPath string, detectDotGit bool) (*git.Repository, error)
• func LoadTemplateData(data string) (*template.Template, error)
• func RPMTemplate() (*template.Template, error)
• func ReleaseTemplate() (*template.Template, error)
• func RepoTemplate() (*template.Template, error)
• type ChangeLog
  • func CreateEntry(date time.Time, version fmt.Stringer, owner string, notes *ChangeLogNotes, ...) (changelog *ChangeLog)
• type ChangeLogChange
• type ChangeLogChanges
• type ChangeLogEntries
  • func AddEntry(gitRepo *git.Repository, version fmt.Stringer, owner string, ...) (cle ChangeLogEntries, err error)
  • func InitChangelog(gitRepo *git.Repository, owner string, notes *ChangeLogNotes, ...) (cle ChangeLogEntries, err error)
  • func Parse(file string) (entries ChangeLogEntries, err error)
  • func (c ChangeLogEntries) Len() int
  • func (c ChangeLogEntries) Less(i, j int) bool
  • func (c *ChangeLogEntries) Save(file string) (err error)
  • func (c ChangeLogEntries) Swap(i, j int)
• type ChangeLogNotes
• type ChangeLogOverridables
• type ChangelogDeb
• type PackageChangeLog
• type User

Variables

var ErrNoCommits = errors.New("no commits found for this entry")

ErrNoCommits happens when no commits are found for a given entry.

Functions

func CommitsBetween

func CommitsBetween(gitRepo *git.Repository, start, end plumbing.Hash, excludeMergeCommits bool) (commits []*object.Commit, err error)

CommitsBetween return the list of commits between two commits.

func DebTemplate

func DebTemplate() (*template.Template, error)

DebTemplate load default debian template.

func FormatChangelog

func FormatChangelog(pkgLogs *PackageChangeLog, tpl *template.Template) (string, error)

FormatChangelog format pkgLogs from a text/template.

func GitHashFotTag

func GitHashFotTag(gitRepo *git.Repository, tagName string) (hash plumbing.Hash, err error)

GitHashFotTag return the git sha for a particular tag.

func GitRepo

func GitRepo(gitPath string, detectDotGit bool) (*git.Repository, error)

GitRepo open a GitRepo to use to build the changelog from.

func LoadTemplateData

func LoadTemplateData(data string) (*template.Template, error)

LoadTemplateData load a template from string with all of the sprig.TxtFuncMap loaded.

func RPMTemplate

func RPMTemplate() (*template.Template, error)

RPMTemplate load default RPM template.

func ReleaseTemplate

func ReleaseTemplate() (*template.Template, error)

ReleaseTemplate load default release template.

func RepoTemplate

func RepoTemplate() (*template.Template, error)

RepoTemplate load default repo template.

Types

type ChangeLog

type ChangeLog struct {
	ChangeLogOverridables `yaml:",inline"`
	Semver                string           `yaml:"semver"`
	Date                  time.Time        `yaml:"date"`
	Packager              string           `yaml:"packager"`
	Notes                 *ChangeLogNotes  `yaml:"notes,omitempty"`
	Changes               ChangeLogChanges `yaml:"changes,omitempty"`
}

ChangeLog a single changelog entry.

func CreateEntry

func CreateEntry(date time.Time, version fmt.Stringer, owner string, notes *ChangeLogNotes, deb *ChangelogDeb, commits []*object.Commit, useConventionalCommits bool) (changelog *ChangeLog)

CreateEntry create a ChangeLog object.

type ChangeLogChange

type ChangeLogChange struct {
	Commit string `yaml:"commit"`
	Note   string `yaml:"note"`
	// Author is the original author of the commit.
	Author *User `yaml:"author,omitempty"`
	// Committer is the one performing the commit, might be different from
	// Author.
	Committer          *User                                   `yaml:"committer,omitempty"`
	ConventionalCommit *conventional_commit.ConventionalCommit `yaml:"conventional_commit,omitempty"`
}

ChangeLogChange an individual change.

type ChangeLogChanges

type ChangeLogChanges []*ChangeLogChange

ChangeLogChanges list of individual changes.

type ChangeLogEntries

type ChangeLogEntries []*ChangeLog

ChangeLogEntries list of ChangeLog entries.

func AddEntry

func AddEntry(
	gitRepo *git.Repository,
	version fmt.Stringer,
	owner string,
	notes *ChangeLogNotes,
	deb *ChangelogDeb,
	current ChangeLogEntries,
	useConventionalCommits bool,
	excludeMergeCommits bool,
) (cle ChangeLogEntries, err error)

AddEntry add a ChangeLog entry to an existing ChangeLogEntries that.

func InitChangelog

func InitChangelog(gitRepo *git.Repository, owner string, notes *ChangeLogNotes, deb *ChangelogDeb, useConventionalCommits bool, excludeMergeCommits bool) (cle ChangeLogEntries, err error)

InitChangelog create a new ChangeLogEntries from a git repo.

func Parse

func Parse(file string) (entries ChangeLogEntries, err error)

Parse parse a changelog.yml into ChangeLogEntries.

func (ChangeLogEntries) Len

func (c ChangeLogEntries) Len() int

Len returns the length of a collection. The number of Version instances on the slice.

func (ChangeLogEntries) Less

func (c ChangeLogEntries) Less(i, j int) bool

Less is needed for the sort interface to compare two Version objects on the slice. If checks if one is less than the other.

func (*ChangeLogEntries) Save

func (c *ChangeLogEntries) Save(file string) (err error)

Save save ChangeLogEntries to a yml file.

func (ChangeLogEntries) Swap

func (c ChangeLogEntries) Swap(i, j int)

Swap is needed for the sort interface to replace the Version objects at two different positions in the slice.

type ChangeLogNotes

type ChangeLogNotes struct {
	Header *string `yaml:"header,omitempty"`
	Footer *string `yaml:"footer,omitempty"`
}

ChangeLogNotes contains a potential header/footer string for output formatting.

type ChangeLogOverridables

type ChangeLogOverridables struct {
	Deb *ChangelogDeb `yaml:"deb,omitempty"`
}

ChangeLogOverridables contains potential format specific fields.

type ChangelogDeb

type ChangelogDeb struct {
	Urgency       string   `yaml:"urgency"`
	Distributions []string `yaml:"distributions"`
}

ChangelogDeb contains fields specific to the debian changelog format https://www.debian.org/doc/debian-policy/ch-source.html#s-dpkgchangelog

type PackageChangeLog

type PackageChangeLog struct {
	Name    string           `yaml:"name"`
	Entries ChangeLogEntries `yaml:"entries"`
}

PackageChangeLog used for the formatting API.

type User

type User struct {
	// Name represents a person name. It is an arbitrary string.
	Name string `yaml:"name"`
	// Email is an email, but it cannot be assumed to be well-formed.
	Email string `yaml:"email"`
}

User is used to identify who created a commit or tag.