BLogic Systems

Git Conventional Commits

Last updated on 
Git Conventional Commits
A Simple Guide to Better Commit Messages

Overview

Conventional Commits is a straightforward system layered on top of your commit messages. It offers a clear set of rules to create a structured, meaningful commit history. This makes it easier to build automated tools, like changelog generators, and pairs seamlessly with Semantic Versioning (SemVer) by tying commits to features, fixes, and breaking changes.

Commit Message Structure

Here’s how to format your commit messages: 

<type>[scope or Jira ticket number]: <description>

[optional body]

[optional footer(s)]

Key Elements and Their Meanings

  • fix: Patches a bug in your code (think SemVer PATCH).
  • feat: Adds a new feature (think SemVer MINOR).
  • BREAKING CHANGE: Signals a major API shift (think SemVer MAJOR). You can mark this in a footer with BREAKING CHANGE: or add a ! after the type/scope (e.g., feat!:). It can apply to any commit type.
  • Other Types: Beyond fix and feat, feel free to use types like build, chore, ci, docs, style, refactor, perf, or test (inspired by Angular’s convention). These don’t directly affect SemVer unless they include a breaking change.
  • Scope: The Jira ticket number (e.g., ABC-123), enclosed in parentheses after the type, links the commit to its issue.
  • Footers: Extra details (e.g., Reviewed-by: Z) can follow a git-trailer-like format.

Examples to Get You Started

Feature with Breaking Change

feat(ABC-123): allow config object to extend other configs

BREAKING CHANGE: `extends` key now pulls in other config files

Breaking Change with Emphasis

feat(DEF-456)!: email customer when product ships

Scoped Breaking Change

feat(API-789)!: email customer when product ships
chore!: drop Node 6 support

BREAKING CHANGE: uses JS features not in Node 6

Simple Fix, No Body

docs: fix typo in CHANGELOG

Scoped Feature

feat(lang): add Polish language support

Detailed Fix with Body and Footers

fix(BUG-404): stop request racing

Add a request ID to track the latest request and ignore outdated responses.  
Timeouts are now obsolete and removed.

Reviewed-by: Z  
Refs: ABC-123

The Rules (Specification)

  • Commits must begin with a type (e.g., feat, fix), followed by the Jira ticket number in parentheses as the scope, an optional ! for breaking changes, and a colon + space.
  • Use feat for new features and fix for bug fixes—mandatory when applicable.
  • The scope must be the Jira ticket number (e.g., ABC-123), tying the commit to its issue in Jira.
  • A short description must follow the colon, summarizing the change.
  • An optional body (after a blank line) can add context in free-form paragraphs.
  • Footers (after a blank line) can include details like Acked-by: or BREAKING CHANGE:. Use hyphens in tokens (e.g., Signed-off-by), except for BREAKING CHANGE.
  • Breaking changes must be flagged—either with a ! before the colon or a BREAKING CHANGE: footer with a description.
  • Other types (e.g., docs) are allowed but don’t inherently impact SemVer.
  • Case is flexible (except BREAKING CHANGE must be uppercase).

Why Use Conventional Commits with Jira?

  • Auto-generate changelogs linked to Jira tickets.
  • Determine version bumps (patch, minor, major) based on commit types.
  • Clearly tie changes to Jira issues for teammates and stakeholders.
  • Trigger automated workflows with Jira integration.
  • Make your project’s history traceable and contributor-friendly.