Skip to content

Conventional Commits

Flowing Code follows an extended version of the Conventional Commits specification, which provides an explicit commit history and dovetails with SemVer by describing features, fixes, and breaking changes in the commit message itself.

Canonical source

Content on this page is derived from the Flowing Code DevelopmentConventions repository (guidelines version 1.0.0-rc.9), licensed under Apache 2.0.

These guidelines encourage logically atomic commits — commits that stand on their own, add value, are small enough to read and review, and represent exactly one logical change that can be independently reverted. Avoid bundling unrelated changes into one commit. There is no hard rule for "small enough" or "valuable enough": use common sense.

Commit message format

Each commit message consists of a header, a body, and a footer. The header has a special format that includes a type, a scope, and a subject. The type and subject are required; the rest is optional.

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

[optional body]

[optional footer(s)]

Commits by the maven-release-plugin are excluded from these guidelines.

1. Type

Required. Must be one of the following:

Commits that contribute to the application source code

Type Description SemVer impact
feat: A new feature MINOR
fix: A bug fix PATCH
perf: A code change that improves performance —
refactor: Improves internal code structure, readability, or maintainability without adding features or fixing bugs PATCH if non-breaking; MAJOR if it breaks a public API
deprecate: Deprecating an existing feature MINOR
remove: Removing a feature MAJOR (always a breaking change)

Commits that contribute to unit tests

  • test: Adding missing tests or refactoring/fixing existing tests.

Commits that contribute to the build process or external dependencies

  • build: Changes to the build process or external dependencies that affect the exported artifacts (those used as final deliverables or consumed by other projects) and, consequently, the applications that rely on them. Correlates with PATCH, MINOR, or MAJOR depending on the nature of the change.
  • ci: Changes to CI configuration or to the build process that have no impact on the exported artifacts or the end user (e.g., code quality metrics, test-only dependencies, build tweaks invisible downstream). Does not correlate with a SemVer increment.

Trivial commits

  • docs: Documentation-only changes.
  • style: Changes that do not affect the meaning of the code (white-space, formatting, missing semicolons, etc.).

Other commits

  • revert: Reverts a previous commit.
  • chore: Changes not covered by other types.
  • WIP: Incomplete changes ("work in progress"). WIP: commits are not required to be logically atomic.

Type values are lowercase.

Breaking changes

An exclamation mark ! after the type (and scope, if present) indicates a breaking change (MAJOR in SemVer). A breaking change can be part of a commit of any type. Additional details can be provided in the footer.

remove!: drop deprecated setFoo method

2. Scope

Optional. Provides additional contextual info. The scope is written in parentheses and consists of a noun describing a section of the codebase. The allowed values and granularity are defined per project.

3. Subject

Required. A succinct description of the change:

  • Use the imperative, present tense: "change", not "changed" nor "changes".
  • Do not capitalize the first letter.
  • No period at the end.
  • The header line (including type and scope) must be less than 72 characters.

A properly formed subject line should always complete the sentence:

If applied, this commit will \<subject>

Examples

Subject Reads as
implement cool feature If applied, this commit will implement cool feature
if applied, this commit will implement cool feature If applied, this commit will if applied, this commit will…
implemented cool feature If applied, this commit will implemented cool feature
implements cool feature If applied, this commit will implements cool feature
cool feature If applied, this commit will cool feature

4. Body

Optional. Should explain the motivation for the change and contrast with previous behavior.

The body is free-form text, may consist of multiple paragraphs separated by blank lines, and may contain URIs or issue links.

Where possible, use the imperative present tense and follow basic grammar rules (capitalized first letter, periods at the end of sentences). This restriction may be relaxed.

Optional. One or more footers may be provided one blank line after the body. Footers contain extra metadata such as breaking-change descriptions, closed issues, and co-authors.

Each footer is a Token: value or Token #value pair. Tokens are case-insensitive except BREAKING CHANGE: which must be uppercase.

Defined footers:

  • BREAKING CHANGE: describes the breaking change introduced by the commit. When used, the breaking-change indicator ! must also appear in the header.
  • Close # links a single closed issue.
  • Co-authored-by: records the name and email of each co-author.

Other footers may be added following the same syntax.

Example

BREAKING CHANGE: description
Close #42
Close #43
Co-authored-by: name <name@example.com>
Co-authored-by: another-name <another-name@example.com>

Revert commits

If a commit reverts a previous one:

  • The type must be revert:.
  • The subject must begin with the type of the reverted commit, followed by the subject of the reverted commit.
  • The message body should contain the SHA of the commit(s) being reverted.

Example

revert: chore: update README.md

Revert commit b3befad91a6e39288ea53d540a4a483b0898fb49.

WIP commits

WIP commits are temporary and are expected to be replaced by a final logically atomic commit before merge.

To mark a commit as work-in-progress:

  • The type must be WIP: (uppercase).
  • The subject must begin with the type of the in-progress commit, followed by its subject.
  • The body may describe the current state of the implementation in addition to the eventual final commit message.

Example

Initial commit with a partial fix:

WIP: fix: prevent orders with negative amount of items

Validation was added in the creation form.
Need to consider the case of editing an existing order.

After completion, the message is rewritten as:

fix: prevent orders with negative amount of items

Add validation in the creation and edition forms.

FAQ

What type to use for visual content changes?

Choose the type that matches the nature of the change:

  • Changes to CSS that affect application code: fix, refactor, etc.
  • Changes to static resources that do not affect code: chore.
  • The style type is reserved for changes that do not affect the meaning of the code (such as formatting).
fix: fix overlapping problem in divs
refactor: use CSS variables instead of hardcoded values
chore: replace the landing page banner
style: format CSS style rules

What type to use when removing a class or method?

  • If the removal takes away a feature, the commit introduces a BREAKING CHANGE and must use remove.
  • Otherwise, it is a refactor.
remove!: remove feature Foo
refactor: remove class Foo

What type to use when fixing trivial code smells?

Trivial changes that preserve logic, structure, and behavior should use style. Use refactor for more complex changes, including those that may introduce breaking changes.

References

Bibliography