Skip to content
Platform Docs

Commit Message Syntax

Our convention for the commit message syntax for our repositories

The Architecture Guild agreed on a commit message syntax for all repositories in Gitlab. It is based on Conventional Commits, with the additional requirement of having a ticket reference in either the commit message description or body.

The commit message has to be structued as follows:

<type>[optional scope]: <description with optional ticket reference>


[optional body with ticket reference if not specified above]


[optional footer(s)]

Regex used for validation:

The regex used for validating commits on the Gitlab server can be found in the platform/push-rules repository.

ℹ️ You can use a tool like regexr.com to explore the regex

From the Conventional Commits Spec:

The commit contains the following structural elements, to communicate intent to the consumers of your library:

  • fix: a commit of the type fix patches a bug in your codebase (this correlates with PATCH in Semantic Versioning)
  • feat: a commit of the type feat introduces a new feature to the codebase (this correlates with MINOR in Semantic Versioning)
  • types other than fix: and feat: are allowed according to the Angular Convention
  • footers other than BREAKING CHANGE: <description> may be provided and follow a convention similar to git trailer format

BREAKING CHANGE: a commit that has a footer BREAKING CHANGE:, or appends a ! after the type/scope, introduces a breaking API change (correlating with MAJOR in Semantic Versioning). A BREAKING CHANGE can be part of commits of any type

Commit Types

The following commit types are allowed, based on the Angular Convention:

  • fix, feat, build, chore, ci, docs, perf, refactor, style, test, release, renovate

Commit Scope

A scope may be provided to a commit’s type, to provide additional contextual information and is contained within parenthesis.

E.g.: feat(parser): add ability to parse arrays, JIRA-123

Best Practices for writing commit messages

  • use the imperative, present tense: "change" not "changed" nor "changes"
  • don't capitalize the first letter
  • do not end the description with a dot (.)
  • use the commit body to explain what and why vs. how

Skip a pipeline

To push a commit without triggering a pipeline, add [ci skip] or [skip ci], using any capitalization, to your commit message. You can read more in the official Gitlab documentation.

Examples

  • no scope, no body
feat: allow provided config object to extend other configs, JIRA-123
  • with scope, no body
docs(lang): correct spelling, JIRA-123
  • with scope and body, ticket reference in description
feat(lang): add Polish language, JIRA-123


As we expanded our service to Poland, we need to support the polish language.
  • with scope and body, ticket reference in body
feat(lang): add Polish language


As we expanded our service to Poland, we need to support the polish language.


See JIRA-123
  • with body, Gitlab issue reference in body
fix: prevent racing of requests


Introduce a request id and a reference to latest request. Dismiss
incoming responses other than from latest request.


Remove timeouts which were used to mitigate the racing issue but are
obsolete now.


Closes #4
  • with body, Gitlab issue reference from other project in body
fix: prevent racing of requests


See https://gitlab.carloop.dev/architecture/architectural-decision-records/-/issues/2

Commits Without Ticket Reference

There are a few cases where a commit does not need a ticket reference:

  • the commit is a merge commit

e.g.:

Merge branch 'feature/ABC-123-test' into 'develop'
  • the commit is an initial commit

e.g.:

Initial commit
  • commits with semantic versions (e.g. release commits):

e.g.:

chore(release): 2.0.0

For more example you can also take a look at our test cases.

References