The format of the Git commit message

As of November 2025, the Drupal Core project adopted Git commit messages formatted to comply with the Conventional Commits specification. This introduced a single 1-line summary of the change at the top, and moved all the credit attributions to the bottom of the commit message as "trailers".

Summary

The format of the message should be:

{commit type}: #{issue ID} One line summary of the change

By: user1
By: user2
...

For example, commit 53a72dc5:

commit 53a72dc5eff2092c0086d8bc39e910cc3762cdf3
Author: Andrei Mateescu <amateescu@729614.no-reply.drupal.org>
Date:   Fri Apr 3 13:25:04 2026 +0300

feat: #3582769 Add clickLink() to HttpKernelUiHelperTrait

By: joachim
By: smustgrave
By: dww
By: amateescu

Commit type

Conventional Commits requires a commit 'type' at the beginning of the message, followed by a :. For example, a bug would use the type 'fix', while a new feature would be 'feat'. The other options are listed below.

The 'type' field can be used to filter and sort commits. This can help maintainers decide if the next release should be a patch release, a new minor version, or a new major version (per Semantic Versioning).

The Conventional Commits specification does not define what the commit type values should be for a project. Drupal core is using the following list (from the conventional changelog metahub project), with the exception that 'chore' is replaced with 'task:

There is also an issue to Add help message or clickable fill for type on the Contribution Record UI.

The issue ID

The commit description begins with # followed by the unique issue identifier (ID). The ID is the last part of the URL for the issue, whether the issue is on Drupal.org or on GitLab. For example, the ID for https://drupal.org/node/3582769 or https://www.drupal.org/project/drupal/issues/3582769 is '3582769', and for https://git.drupalcode.org/project/contribution_records/-/work_items/354... it is '3542433'.

URL redirection and GitLab

As issues are migrated to GitLab "work items", these issue IDs are preserved. URLs such as https://www.drupal.org/node/3542433 or https://www.drupal.org/i/3542433 redirect to the migrated GitLab issue, which has the same issue ID: https://git.drupalcode.org/project/contribution_records/-/work_items/354...

However, once a project has migrated to use GitLab for issue tracking, IDs are no longer unique across all projects, but are numbered per-project, and will increment from the highest migrated issue node ID. After projects migrate to GitLab, we will start to have multiple "work items" with the same ID from different projects. Drupal.org will not know about new GitLab issues. So, going forward, you will not be able to rely on visiting drupal.org/node/X to find the issue that corresponds to a specific Git commit.

Once a project migrates to GitLab issues, you can get to the correct issue for a given commit using a URL like https://git.drupalcode.org/project/[project_name]/-/work_items/[ID]. For example, for issue ID '3542433' from the 'contribution_records' project, the correct URL is: https://git.drupalcode.org/project/contribution_records/-/work_items/354....

The By: lines and credit

The 'By' lines are for listing the contributors who helped complete the issue. These are not used to determine issue credit. Drupal.org issue credit is entirely based on the Contribution Record linked from every issue.

Maintainers should review the issue in detail, and correctly fill out the Contribution Record for that issue before committing. The information from the Contribution Record is used to automatically suggest a commit message, although you must manually specify the correct commit type.

Having accurate attributions in the Git history is important for a number of reasons. Do not rely entirely on the Contribution Record. Many things can be parsing the Git history that will not integrate with the Drupal.org credit system. The commit messages are available while working offline or even if Drupal.org is down.

Creating 'By' lines by hand

• Use Drupal.org user names, not GitLab user names. Although for many users, the names are the same, sometimes they do not match. The contribution record uses the Drupal.org user names. If you are adding your own trailers, do the same. Being consistent will allow tools that parse these messages (for example, to create release notes) to always correctly link to the right users.
• Do not use @username in these lines. Drupal's GitLab instance will recognize these username mentions and link commits to profiles (if the GitLab username matches the Drupal.org username, which is not always true). However, when a repository is mirrored to another provider, such as GitHub, the @username will be parsed as a GitHub user, not a Drupal GitLab user. This results in confusion and spam.
• Maintainers can use anything they like to be more precise about who was involved in that commit and how they participated. Some common trailer keys include: Co-authored-by:, Reported-by:, Reviewed-by:, and so on. For example, commit 49d3af921 from the Pathologic module:

commit 49d3af921f6cc82dd5bae405c205c93868311e76
Author: Pierre Rudloff <contact@rudloff.pro>
Date:   Sun Mar 15 16:06:38 2026 -1000

    fix: #3354345 Pathologic breaks srcset when used with multipliers

    Co-authored-by: prudloff
    Co-authored-by: edwtorba
    Co-authored-by: dww
    Reported-by: dsnopek

For more gory details about Git trailers, you can check out the official docs for the git interpret-trailers command.

Release notes

Once a project is consistently using Conventional Commits, there are a number of tools to help manage releases and create release notes. However, the most basic possible "tool" for this would be the following UNIX 1-liner:

git log --pretty=format:%s previousVersion..currentVersion | sort

This will group all commits between 2 versions into the types of commits, and order them by issue ID within each type. For example:

git log --pretty=format:%s 10.6.1..10.6.2 | sort
Back to dev.
Drupal 10.6.2
fix: #3551373 [random test failure] ManageDisplayTest testFormatterUI() and testWidgetUI()
fix: #3565218 [random test failure] ResponsiveImageFieldUiTest::testResponsiveImageFormatterUi()
task: #3557585 [backport to 11.2, 10.6, and 10.5] Update to Composer 2.9.2
task: #3565943 [backport] [security hardening] Update composer to 2.9.3

As expected with a patch release (10.6.2, not 10.7.0), this release does not contain any feat commits (new features), only fix and task.

History

For background on how this format was decided, you can review the following issues:

• #2323715: [policy, no patch] Determine format for commit credit for individuals/organizations/customers
• #3439331: [policy] Decide on format of commit message
• #3543076: Simplify agreed commit format and comply with Conventional commits spec