Skip to content

Commit Message Guidelines

Follow these guidelines precisely — the format lets us automatically deploy OneConnect and document each deployment's changes.

Commit Message Format

Commit messages follow the Conventional Commits standard.

Each message has a header, a body, and a footer. The header includes a type, a Jira project key, and a subject:

<type>(<jira-project-key>): <subject>

<body>

<footer>
<Reviewed-by: Greig Hamilton <greig.hamilton@gmail.com>>

Separate the header from the body, and the body from the footer, with a blank line.

Keep all lines to 72 characters or fewer — longer lines are harder to read.

Examples: 

docs(OC-1234): update development guidelines

Reviewed-by: Greig Hamilton <greig.hamilton@gmail.com>
Change-Id: If47eb75a14d424859c2c515ad922e480e46154b3

fix(OC-5678): handle missing email address

When the email address is not returned by userManagement service don't
attempt to send an email to the user.

Reviewed-by: Greig Hamilton <greig.hamilton@gmail.com>
Change-Id: If47eb75a14d424859c2c515ad922e480e46154b4

Revert

To revert a previous commit, begin with revert:, followed by the header of the reverted commit. In the body, write: This reverts commit <hash>., where the hash is the SHA of the commit being reverted.

Type

Use one of the following types (all lowercase):

  • build: Changes that affect the build system or external dependencies
  • chore: Maintenance tasks that don't modify src or test files
  • ci: Changes to our CI configuration files and scripts
  • docs: Documentation only changes
  • feat: A new feature
  • fix: A bug fix
  • perf: A code change that improves performance
  • refactor: A code change that neither fixes a bug nor adds a feature
  • style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
  • test: Adding missing tests or correcting existing tests
  • revert: Revert a commit

Subject

Write a succinct description of the change:

  • Use the imperative, present tense: "change" not "changed" nor "changes"
  • Don't capitalize the first letter
  • No dot (.) at the end

Body

Use the imperative, present tense here too: "change" not "changed" nor "changes". Include the motivation for the change and contrast it with previous behavior.

OneConnect generally follows the AW+ commit body style. Refer to Commit body guide

Informative commit messages are particularly important when changes affect external teams.

If a commit has negative consequences (such as reduced performance or increased maintenance burden), mention them in the body.

The footer must contain:

  • BREAKING CHANGE: Information about any breaking changes (only include if there are breaking changes)
  • Reviewed-by: Each reviewer of the patch
  • Change-Id: The Gerrit change-id that is automatically added to the bottom of the patch. (Only required for patches reviewed with Gerrit. Github repos don't need this.)

Put breaking changes first — readers see them immediately, and they relate most closely to the commit body. Include this field whenever a commit has breaking changes: the automated deployment tools read it to decide whether to deploy the patch immediately.

A breaking change is: - A change that requires the deployment manifest to be updated - Removing an API

BREAKING CHANGE: must be followed by a space or two newlines.

Examples:

feat(OC-1234): add multi-factor authentication

This introduces a new security layer for all login requests.

BREAKING CHANGE: the `login` endpoint now requires an `otp` field.
Reviewed-by: Alice <alice@example.com>
Reviewed-by: Bob <bob@example.com>
Change-Id: Ic8aaa0728a43936cd4c6e1ed590e01ba8f0fbf5b
Multi-line and multi-paragraph breaking changes are also supported: 
feat(OC-1234): add multi-factor authentication

This introduces a new security layer for all login requests.

BREAKING CHANGE: the `login` endpoint now requires an `otp` field.

It is also possible to add extra detail about the breaking change. This
can be over many lines and multiple paragraphs if required.

Reviewed-by: Alice <alice@example.com>
Reviewed-by: Bob <bob@example.com>
Change-Id: Ic8aaa0728a43936cd4c6e1ed590e01ba8f0fbf5b