Generate and Release a Changelog

Published: at 14:48

In this post I will show you how to automatically generate a changelog from your git commit history using standard-version for commit guidelines.

Table of contents

Open Table of contents

Structuring commit messages with conventional commits

The Conventional Commits specification is a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history; which makes it easier to write automated tools on top of. This convention dovetails with SemVer, by describing the features, fixes, and breaking changes made in commit messages.

The commit message should be structured as follows:

feat(home): add function to handle form
^--^  ^--^  ^------------^
|     |     |
|     |     +-> Summary in present tense.
|     |
|     +-> Scope: The scope could be anything specifying place of the commit change, scope is optional.
+-------> Type: test, feat, fix, chore, docs, refactor, style, ci and perf.


BREAKING CHANGE: isolate scope bindings definition has changed.
^------------^
|
+-------> Footer: The footer is optional and is used to reference issue tracker IDs or to provide a BREAKING CHANGE.

The commit contains the following structural elements, to communicate intent to the consumers of your library:

  • fix: a commit of the type fix patches a bug in your codebase (this correlates with PATCH in semantic versioning).
  • feat: a commit of the type feat introduces a new feature to the codebase (this correlates with MINOR in semantic versioning).
  • BREAKING CHANGE: a commit that has the text BREAKING CHANGE: at the beginning of its optional body or footer section introduces a breaking API change (correlating with MAJOR in semantic versioning). A breaking change can be part of commits of any type.
  • types other than fix: and feat: are allowed, for example @commitlint/config-conventional (based on the the Angular convention) recommends build:, chore:, ci:, docs:, style:, refactor:, perf:, test:, and others.
  • footers other than BREAKING CHANGE: may be provided and follow a convention similar to git trailer format.

Commit message examples


# commit message with just type and summary
feat: add function to handle form

# commit message with type, scope and summary
feat(home): create header and footer components

# commit message with scope and BREAKING CHANGE
refactor(api): remove deprecated endpoint

BREAKING CHANGE: The /api/users endpoint has been replaced with /api/accounts

Using standard-version

To use standard-version, you need to install as a dev dependency in your project:


pnpm i -D standard-version

Install commitizen and cz-conventional-changelog globally:


pnpm i -g commitizen cz-conventional-changelog

In the project root directory, run the following command:


commitizen init cz-conventional-changelog --save-dev --save-exact

You will need to add a script to your package.json file:

...
  "scripts": {
    "commit": "cz",
    "release": "standard-version"
  }
...

Creating a changelog

Create a dummy file called awesome-feature.txt and commit it:


touch awesome-feature.txt
git add awesome-feature.txt
git-cz --non-interactive --type=feat --subject="add awesome feature"

Now, you can run the release script:


pnpm run release

Now, you can see the CHANGELOG.md generated which includes the changes made. The CHANGELOG.md file will look something like this:

# Changelog

All notable changes to this project will be documented in this file. See \[standard-version\](https://github.com/conventional-changelog/standard-version) for commit guidelines.

## 1.0.1 (2024-01-21)

### Features

- **awesome-feature:** add awesome feature [f1b4b3f]

You can also see the list of recent commits by running the following command:


git log --pretty=format:"%h - %an, %ar : %s" --graph

The output will look something like this:


* f1b4b3f - Silas Rodrigues, 2 minutes ago : add awesome feature

Why use conventional commits?

  • Automatically generating CHANGELOGs.
  • Automatically determining a semantic version bump (based on the types of commits landed).
  • Communicating the nature of changes to teammates, the public, and other stakeholders.
  • Triggering build and publish processes.
  • Making it easier for people to contribute to your projects, by allowing them to explore a more structured commit history.

Conclusion

In this post, I showed you how to automatically generate a changelog from your git commit history using standard-version for commit guidelines and how to install commitizen and cz-conventional-changelog globally.

References