Commits With Character

A simple convention for conveying semantic versioning to both humans and automated systems via commit messages

General commit guidelines

Separate subject from body with a blank line

The first line of the commit message is the subject, which should be a short, descriptive summary of the changes. The body, which provides more detailed information, should be separated from the subject by a blank line.

Keep the subject to 50 characters or less if possible

The subject line should be concise and to the point, as it is often used in various Git tools and interfaces. Keeping it under 50 characters ensures readability and clarity.

Capitalise the subject

The subject line should be capitalised, as it is treated as a sentence. This helps maintain a consistent style throughout the commit history.

Do not end the subject line with a fullstop/period

Subject lines benefit from brevity; trailing punctuation is superfluous, especially when striving to maintain a concise 50-character limit.

Use the imperative mood in the subject

The subject line should be written in the imperative mood, as if you're giving a command. For example, "Fix bug" instead of "Fixed bug" or "Fixes bug"

Wrap the body at 72 characters

The body of the commit message should be wrapped at 72 characters to improve readability and make it easier to view the commit history in various tools.

Use the body to explain how it worked before, what has changed, and how it works now

The body of the commit message should focus on explaining the changes made and the reasoning behind them, rather than describing the implementation details.

Commits With Character

Prefix consumer-affecting commits with a semantic character

Use a character prefix, followed by a space, to inform your consumers about the intent of the work.

  • !
    An incompatible change has been made to your API; a breaking change (MAJOR).
  • ^
    Backward compatible functionality added to your API; a new feature (MINOR).
  • ~
    Backward compatible bug fix made to your API, or a code change that improves performance; any non-feature that requires a release (PATCH).

Use a scope to provide additional contextual information

A scope is a noun describing a section of the codebase the commit relates to, and is placed after the character, if provided, but before the subject, and is followed by a colon and a space.

Examples

Non-feature improvement

~ Fix typo in response from parser

Scoped breaking change

! faux-util: Delete deprecated options

New feature with body

^ Add automated data validation for user inputs

Previously, user inputs underwent manual validation, leading to
occasional errors and data inconsistencies. Users had to carefully
review inputs before submission, which was time-consuming and prone to
oversight.

Now, the system checks inputs against predefined criteria in real-time,
flagging discrepancies and providing error messages. This ensures data
integrity and reduces errors, improving overall system reliability.

Non-consumer affecting change

Fix 404 credit links in CONTRIBUTING

Non-consumer affecting scoped change

acme-tool: Remove superfluous semicolons

About

The Commits With Character specification draws inspiration from Conventional Commits, in that it also serves the purpose of adding semantic significance to a commit message. However, it distinguishes itself by endorsing and expanding upon the commit guidelines outlined in the original Git Book, thereby steering clear of commit categorisation.

If you know Semantic Versioning, you know Commits With Character.

This simple addition is for projects that do not need the full power of Changesets (which is highly recommended for complex team projects), are happy to drive a changelog and release from commit messages, but would rather not have the overhead of Conventional Commits.

Automation

The Semantic Release tool can be easily configured to use Commits with Character. Here's an example configuration file:

.releaserc.yaml
plugins:
  # Extracts commits starting with ~, ^, or !
  - path: '@semantic-release/commit-analyzer'
    parserOpts:
      headerPattern: '^([!^~])(?: (.*):)? (.*)$'
      headerCorrespondence:
        - type
        - scope
        - subject
    # The type can be a glob pattern so the characters need to be escaped.
    releaseRules:
      - release: patch
        type: "\\~"
      - release: minor
        type: "\\^"
      - release: major
        type: "\\!"

  # Generates release notes using Major, Minor, and Patch sections.
  - path: '@semantic-release/release-notes-generator'
    parserOpts:
      headerPattern: '^([!^~])(?: (.*):)? (.*)$'
      headerCorrespondence:
        - type
        - scope
        - subject
    preset: conventionalcommits
    presetConfig:
      types:
        - hidden: false
          section: Major
          type: '!'
        - hidden: false
          section: Minor
          type: '^'
        - hidden: false
          section: Patch
          type: '~'

  # Uses pnpm to bump and publish the release.
  - path: '@semantic-release/exec'
    prepareCmd: 'pnpm version ${nextRelease.version} --git-tag-version=false'
    publishCmd: 'pnpm publish --no-git-checks'

  # Saves the release notes to GutHub's Releases page.
  - '@semantic-release/github'

  # Writes to the CHANGELOG.md file.
  - path: '@semantic-release/changelog'
    changelogFile: CHANGELOG.md
    changelogTitle: '# Changelog'

  # Commits the changes with a "vX.Y.Z" message.
  - path: '@semantic-release/git'
    assets:
      - CHANGELOG.md
      - package.json
    message: |
      v${nextRelease.version}

      [skip ci]
Release command
pnpx --package semantic-release@25 \
     --package conventional-changelog-conventionalcommits@9 \
     --package @semantic-release/changelog@7 \
     --package @semantic-release/git@11 \
     --package @semantic-release/exec@7 semantic-release

"But I love Conventional Commits and Commits With Character!"

Whilst it is not recommended, if you really feel the need to categorise every commit with a prefix, here's some suggestions you can use for all non-consumer affecting commits.

PrefixDescription
=A source code change that doesn’t fix a bug, doesn’t add a feature, doesn’t change performance, or doesn't change the meaning of the code (comments, white-space, formatting, missing semi-colons, etc).
?Add missing tests or correct existing tests.
%Documentation only changes.
$Changes that affect the build system or external dependencies (development dependencies), or changes to CI configuration files and scripts. Can be used for general project maintenance tasks.
>Release and merge commits.
<Revert commits.
github.com/commits-with-character