Conventional commits

Knope supports a subset of conventional commits, a way of encoding changelog & version information into commit messages. This document describes how conventional commits work in Knope, not the full scope of the larger project.

Tip

You can disable conventional commits by configuring the PrepareRelease step.

The first line

Every conventional commit must start with a type, followed by an optional scope, then an optional exclamation point, then a colon, then a space, then a summary of the change.

<type>[optional scope][!]: <summary>

Any commit without a first line structured like that isn’t a conventional commit.

Examples of valid first lines

Basic

feat: add a new feature

With scope

feat(parser): add a new feature

With exclamation point

feat!: add a new feature

With scope and exclamation point

feat!(parser): add a new feature

Special types

If the type of the conventional commit is feat, the change is a minor change (for the purposes of semantic versioning). Knope will add the summary to the “Features” section of the changelog.

If the type is fix, the change is a patch change and Knope will add the summary to the “Fixes” section of the changelog.

Knope ignores every other type, so they have no impact on the changelog or versioning. However, the commit is still a conventional commit, so the footers could impact the changelog and version.

Exclamation point

If the first line of the commit has an exclamation point right before the colon, the commit is a major change. Knope will add the summary to the “Breaking changes” section of the changelog. This is regardless of the type of the commit.

Scopes

A scope is any text immediately after the type within parentheses. The commit message feat(parser): add a new feature has a scope of parser. Scopes limit the impact of a change in multi-package repositories. See the releasing multiple packages tutorial for more information.

The body

After the first line, every line is part of the body until the first footer. Knope ignores commit bodies.

Footers

A footer has the format <key>: <value>. You can have as many footers as you want, one per line. By default, Knope only checks for these footers:

BREAKING CHANGE: This footer represents a major change. The <value> will be in the “Breaking Changes” section of the changelog.

Changelog-Note: The <value> will be in the “Notes” section of the changelog, for semantic versioning purposes this is a patch change.

You can also use custom footers to add info to custom changelog sections, see the recipes on customizing the changelog for more info.

Full example

feat(parser)!: Add a new feature

This is the body

and so it will be ignored

BREAKING CHANGE: Another breaking change
Changelog-Note: A note

This is a conventional commit with a type of feat, a scope of parser, and an exclamation point. There are two footers: BREAKING CHANGE with the value of “Another breaking change” and Changelog-Note with the value of “A note.”

Because of the exclamation point, “Add a new feature” will be in the “Breaking Changes” section of the changelog. If that exclamation point wasn’t there, it would be in the “Features” section of the changelog.

The parser scope will limit all of these changes (including the footers) to packages which have a parser scope and packages which have no scopes.

The “Another breaking change” footer will be in the “Breaking Changes” section of the changelog,

The “A note” footer will be in the “Notes” section of the changelog.