Title: Commit Messages
Author: Helen Hou-Sandi
Published: September 4, 2015
Last modified: August 17, 2026

---

# Commit Messages

## In this article

 * [Format](https://make.wordpress.org/core/handbook/best-practices/commit-messages/?output_format=md#format)
    - [Global Guidelines](https://make.wordpress.org/core/handbook/best-practices/commit-messages/?output_format=md#global-guidelines)
    - [Brief summary](https://make.wordpress.org/core/handbook/best-practices/commit-messages/?output_format=md#brief-summary)
    - [Description](https://make.wordpress.org/core/handbook/best-practices/commit-messages/?output_format=md#description)
    - [Developed in, discussed in](https://make.wordpress.org/core/handbook/best-practices/commit-messages/?output_format=md#developed-in-discussed-in)
    - [Follow-up to](https://make.wordpress.org/core/handbook/best-practices/commit-messages/?output_format=md#follow-up-to)
    - [Reviewed By and Merges](https://make.wordpress.org/core/handbook/best-practices/commit-messages/?output_format=md#reviewed-by-and-merges)
    - [Props](https://make.wordpress.org/core/handbook/best-practices/commit-messages/?output_format=md#props)
    - [Ticket references](https://make.wordpress.org/core/handbook/best-practices/commit-messages/?output_format=md#ticket-references)
 * [Example](https://make.wordpress.org/core/handbook/best-practices/commit-messages/?output_format=md#example)
 * [Automatically Pre-fill Commit Message](https://make.wordpress.org/core/handbook/best-practices/commit-messages/?output_format=md#automatically-pre-fill-commit-message)
 * [Other tips for committers](https://make.wordpress.org/core/handbook/best-practices/commit-messages/?output_format=md#other-tips-for-committers)
    - [Before a commit](https://make.wordpress.org/core/handbook/best-practices/commit-messages/?output_format=md#before-a-commit)
    - [After a commit](https://make.wordpress.org/core/handbook/best-practices/commit-messages/?output_format=md#after-a-commit)
 * [More resources](https://make.wordpress.org/core/handbook/best-practices/commit-messages/?output_format=md#more-resources)

[↑ Back to top](https://make.wordpress.org/core/handbook/best-practices/commit-messages/?output_format=md#wp--skip-link--target)

Commit messages are a critical aspect of how WordPress is developed. They are an
integral part of the project’s history, along with the changesets themselves. We
write commit messages for multiple audiences: contemporaries (fellow coreCore Core
is the set of software required to run WordPress. The Core Development Team builds
WordPress. developers, pluginPlugin A plugin is a piece of software containing a
group of functions that can be added to a WordPress website. They can extend functionality
or add new features to your WordPress websites. WordPress plugins are written in
the PHP programming language and integrate seamlessly with WordPress. These can 
be free in the WordPress.org Plugin Directory [https://wordpress.org/plugins/](https://wordpress.org/plugins/)
or can be cost-based plugin from a third-party. developers, anybody following along
with core development), future contributors, and computers. Good commit messages
serve each of these audiences well. They describe the _what_ and the _why_ of the
changeset; the _how_ is described by the diff itself.

Even if you are not a committercommitter A developer with commit access. WordPress
has five lead developers and four permanent core developers with commit access. 
Additionally, the project usually has a few guest or component committers – a developer
receiving commit access, generally for a single release cycle (sometimes renewed)
and/or for a specific component., you can make use of these guidelines while contributing
to WordPress, as well as in your own projects. By describing your patchpatch A special
text file that describes changes to code, by identifying the files and lines which
are added, removed, and altered. It may also be referred to as a **diff**. A patch
can be _applied_ to a codebase for testing. in a way that is sensitive to the concerns
outlined here – or even drafting a commit message yourself – you make it easier 
for the committer process your contribution quickly.

Remember: Do not commit to multiple branches in the same commit. This will, at a
minimum, break the GitGit Git is a free and open source distributed version control
system designed to handle everything from small to very large projects with speed
and efficiency. Git is easy to learn and has a tiny footprint with lightning fast
performance. Most modern plugin and theme development is being done with this version
control system. [https://git-scm.com/](https://git-scm.com/) mirrors.

## 󠀁[Format](https://make.wordpress.org/core/handbook/best-practices/commit-messages/?output_format=md#format)󠁿

The full format for a commit message is as follows:

    ```wp-block-code
    Component: Brief summary.

    Longer description with more details, such as a `new_hook` being introduced with the context of a `$post` and a `$screen`.

    More paragraphs can be added as needed.

    Example usage:

    {{{
    // Multi-line code snippet.
    $add_filter( 'some_new_filter', 'some_filter_callback' );
    }}}

    Developed in: https://github.com/WordPress/wordpress-develop/pull/6395
    Discussed in: https://wordpress.slack.com/archives/C18723MQ8/p1782986746738579

    Follow-up to r27195, r41062.

    Reviewed by a-fellow-committer, maybe-multiple.
    Merges r26851 to the x.x branch.

    Props person, another.
    Fixes #30000. See #20202, #105.
    ```

### 󠀁[Global Guidelines](https://make.wordpress.org/core/handbook/best-practices/commit-messages/?output_format=md#global-guidelines)󠁿

 * Each line should begin with a capital letter and end with a full stop/period.
 * Code, such as the name of a function or a hook, should appear inside backticks,
   to ensure proper formatting in TracTrac An open source project by Edgewall Software
   that serves as a bug tracker and project management tool for WordPress. and SlackSlack
   Slack is a Collaborative Group Chat Platform [https://slack.com/](https://slack.com/).
   The WordPress community has its own Slack Channel at [https://make.wordpress.org/chat/](https://make.wordpress.org/chat/).
 * Outside of the brief summary, there are no character limits. Don’t manually wrap
   lines.
 * Pay attention to places that should have a blank line before them and areas that
   should not.
 * Ticketticket Created for both bug reports and feature development on the bug 
   tracker. numbers are preceded by a number sign (`#20202`) and changeset by `r`(`
   r30000`). They will auto-link in Trac, Slack, GitHubGitHub GitHub is a website
   that offers online implementation of git repositories that can easily be shared,
   copied and modified by other developers. Public repositories are free to host,
   private repositories require a paid subscription. GitHub introduced the concept
   of the ‘pull request’ where code changes done in branches by contributors can
   be reviewed and discussed before being merged by the repository owner. [https://github.com/](https://github.com/),
   and here on make/core.
    - Do not use a hashtag followed by a string of numbers for anything other than
      a link to a trac ticket.
 * Outside of the `props` section, avoid using the word `props` in order to not 
   confuse the tools that generate contributor statistics. If talking about properties,
   use the full word. Otherwise, consult a [thesaurus](https://www.thesaurus.com/browse/prop).

### 󠀁[Brief summary](https://make.wordpress.org/core/handbook/best-practices/commit-messages/?output_format=md#brief-summary)󠁿

The first line of a commit message is a brief summary of the changeset. The brief
summary is used for email subject lines, Trac changelogs, and features prominently
in most VCS log formats, such as `git log --format=oneline`. The high visibility
of the summary makes it critical to craft something that is as descriptive as possible
within space limits.

#### 󠀁[Guidelines](https://make.wordpress.org/core/handbook/best-practices/commit-messages/?output_format=md#guidelines)󠁿

 * Must be one line; no line breaks.
 * Aim for around 50 characters or less, stopping at 70. This is important because
   log-viewing tools nearly all expect the first line of commit messages to fit 
   within these limits. This difficult restriction may force you to think critically
   about the essence of your commit; if you can’t describe the change in a short
   sentence, the commit may not be atomic enough.
 * You may prefix the summary with the component or focus of the change. Such a 
   prefix may make it easier for contributors to scan the changelog for commits 
   of interest. See [r33901](https://core.trac.wordpress.org/changeset/33901), [r33883](https://core.trac.wordpress.org/changeset/33883),
   [r33848](https://core.trac.wordpress.org/changeset/33848) for some examples. 
   Note that the prefix counts toward the 50/70 character count.
 * Use the imperative mood when possible: “Relax term ID comparisons…” instead of“
   Relaxes term ID comparisons…”

### 󠀁[Description](https://make.wordpress.org/core/handbook/best-practices/commit-messages/?output_format=md#description)󠁿

The longer description of a commit should include more details about the commit 
and its repercussions for developers. These may include new hooksHooks In WordPress
theme and development, hooks are functions that can be applied to an action or a
Filter in WordPress. Actions are functions performed when a certain event occurs
in WordPress. Filters allow you to modify certain functions. Arguments used to hook
both filters and actions look the same., “gotchas”, other solutions that were considered,
or backstory. Consider your audiences when deciding what should go into the description:
developers following along with the commit mailing list, volunteers collating information
for each release’s dev notesdev note Each important change in WordPress Core is 
documented in a developers note, (usually called dev note). Good dev notes generally
include a description of the change, the decision that led to this change, and a
description of how developers are supposed to work with that change. Dev notes are
published on Make/Core blog during the beta phase of WordPress release cycle. Publishing
dev notes is particularly important when plugin/theme authors and WordPress developers
need to be aware of those changes.In general, all dev notes are compiled into a 
Field Guide at the beginning of the release candidate phase. and WordPress Core 
Weekly, and future code archaeologists trying to figure out who did what and **why**.

#### 󠀁[Guidelines](https://make.wordpress.org/core/handbook/best-practices/commit-messages/?output_format=md#guidelines-2)󠁿

 * Must be separated from the summary by a blank line.
 * Can be multiple paragraphs if necessary, separated by blank lines. It is not 
   unreasonable for a commit message to be more verbose than the final changeset
   itself.
 * Unlike the Summary, lines should not be manually wrapped – log viewers can take
   care of wrapping the description themselves if they need to.
 * At times it is best to use lists instead of paragraphs, this is at the discretion
   of the committer.
 * The words `props`, `backport`, `backports` should be avoided.

### 󠀁[Developed in, discussed in](https://make.wordpress.org/core/handbook/best-practices/commit-messages/?output_format=md#developed-in-discussed-in)󠁿

Use these optional sections to include relevant links. For example, “developed in”
is useful to link to a GitHub pull request where a change was developed.

### 󠀁[Follow-up to](https://make.wordpress.org/core/handbook/best-practices/commit-messages/?output_format=md#follow-up-to)󠁿

When the commit is directly related to some previous work such as adding tests for
a specific changeset or fast follow fixes, “Follow-up to” must be used with a link
to those changesets. If you are backporting a commit, please follow the “Reviewed
By and Merges” section instead.

#### 󠀁[Guidelines](https://make.wordpress.org/core/handbook/best-practices/commit-messages/?output_format=md#guidelines-3)󠁿

 * Must be preceded by a blank line.
 * Must prefix changesets with `r` (`r30000`).

### 󠀁[Reviewed By and Merges](https://make.wordpress.org/core/handbook/best-practices/commit-messages/?output_format=md#reviewed-by-and-merges)󠁿

When [backporting code](https://make.wordpress.org/core/handbook/best-practices/backporting-commits/),
use the `Reviewed By and Merges` section to indicate the code that is being merged
and who reviewed it. Please specify the branchbranch A directory in Subversion. 
WordPress uses branches to store the latest development code for each major release(
3.9, 4.0, etc.). Branches are then updated with code for any minor releases of that
branch. Sometimes, a major version of WordPress and its minor versions are collectively
referred to as a “branch”, such as “the 4.0 branch”. this is being merged into to
help people seeing the commit in chat or email. It’s a best practice for the review
to be noted in trac with the `[dev-reviewed](https://make.wordpress.org/core/handbook/contribute/trac/keywords/#action-based-keywords)`
keyword.

#### 󠀁[Guidelines](https://make.wordpress.org/core/handbook/best-practices/commit-messages/?output_format=md#guidelines-4)󠁿

 * This set of two lines must be preceded by a blank line.
 * There should be a hard return between the Reviewed By and Merges lines but there
   must not be a blank line between them.
 * Multiple core committers may be mentioned as reviewers. When this happens, please
   separate them with a comma.
 * While the task of moving the code is called backporting, the words `backport`,`
   backports`, and `backporting` should not be used anywhere in the commit message.
 * When backporting a commit made by another committer, add their username to the
   list of props if it is not already included.

### 󠀁[Props](https://make.wordpress.org/core/handbook/best-practices/commit-messages/?output_format=md#props)󠁿

Props should be given to all those who contributed to the final commit, whether 
through patches, refreshed patches, code suggested otherwise, design, writing, user
testing, or other significant investments of time and effort. Usernames are parsed
for the credits list and WordPress.orgWordPress.org The community site where WordPress
code is created and shared by the users. This is where you can download the source
code for WordPress core, plugins and themes as well as the central location for 
community conversations and organization. [https://wordpress.org/](https://wordpress.org/)
profiles.

In the case of bugbug A bug is an error or unexpected result. Performance improvements,
code optimization, and are considered enhancements, not defects. After feature freeze,
only bugs are dealt with, with regressions (adverse changes from the previous version)
being the highest priority. reports, props should also be given to the reporter 
of the bug.

Check any tickets which were closed as a duplicate in case they contain contributions
that warrant props too.

#### 󠀁[Guidelines](https://make.wordpress.org/core/handbook/best-practices/commit-messages/?output_format=md#guidelines-5)󠁿

 * Props must be preceded by a blank line.
 * There should be no semi-colon (`:`) between “Props” and the w.org usernames.
 * Usernames must not start with an @ (at) sign.
 * Separate usernames by comma + space. Think: `/^Props (\s*([^,]+),?)+$/`
 * Copy/paste usernames to avoid typos. (Sorry, rmccue; or is that rmmcue?)
 * If the user has a space in their displayed name, use the slug from their w.org
   profile URLURL A specific web address of a website or web page on the Internet,
   such as a website’s URL www.wordpress.org. For example, Frank Klein on Trac should
   get props as frank-klein.
 * The props line should only include the word props, wordpress.org usernames, spaces,
   and punctuation.
 * The `props` line must end with a period.

#### 󠀁[Self props](https://make.wordpress.org/core/handbook/best-practices/commit-messages/?output_format=md#self-props)󠁿

 * Prop yourself when the commit is the product of huge efforts involving multiple
   people, such a major feature, APIAPI An API or Application Programming Interface
   is a software intermediary that allows programs to interact with each other and
   share data in limited, clearly defined ways., or particularly nasty bug.
 * Generally, giving contributors feedback on patches and giving them a chance to
   iterate is the recommended process. However, on the occasions where you as the
   committer complete the idea of a patch, you could write “props X for initial 
   patch.”
 * It is normal for committers to adjust style or rearrange logic before a commit,
   or to account for a simple edge case. In these instances, omit yourself. Your
   name on the commit implies that you’ve reviewed and tested it, which is just 
   as important as the contents of the commit.
 * If committing your own code, props are assumed, so omit yourself here as well.

For a more detailed guide about giving props to contributors, see the [Contributor Attribution (“Props”) page in the handbook](https://make.wordpress.org/core/handbook/best-practices/contributor-attribution-props/).

### 󠀁[Ticket references](https://make.wordpress.org/core/handbook/best-practices/commit-messages/?output_format=md#ticket-references)󠁿

Trac will add commit messages as comments on all tickets referenced as “fixes” or“
see”. If a commit message contains the text “Fixes [#12345](https://core.trac.wordpress.org/ticket/12345)“,
Trac will close ticket [#12345](https://core.trac.wordpress.org/ticket/12345) and
assign you as the owner if there isn’t one already.

#### 󠀁[Guidelines](https://make.wordpress.org/core/handbook/best-practices/commit-messages/?output_format=md#guidelines-6)󠁿

 * Ticket references should be on their own line directly below any props. If there
   are no props, an empty newline should separate it from the content above.
 * Multiple tickets should be separated by a comma + space.
 * If referencing both fixed and related tickets, begin with “Fixes” and end each
   set with a period, e.g. “Fixes [#19867](https://core.trac.wordpress.org/ticket/19867),
   [#9864](https://core.trac.wordpress.org/ticket/9864). See [#31696](https://core.trac.wordpress.org/ticket/31696).”.
   If there are many items in a set, put it on its own line.
 * If you forget to include a ticket number, comment on the ticket (e.g., “Fixed
   in [r30000](https://core.trac.wordpress.org/changeset/30000)” with an optional
   copy of the commit message to help ensure traceability.

## 󠀁[Example](https://make.wordpress.org/core/handbook/best-practices/commit-messages/?output_format=md#example)󠁿

Bad:

    ```wp-block-code
    Don't use strict comparisons for term IDs. props booneiscool. fixes #3398.
    ```

Meh:

    ```wp-block-code
    Fixing `wp_dropdown_categories()` and other places that use term IDs.

    props boonerocks. fixes #20000.
    ```

Good:

    ```wp-block-code
    Taxonomy: Relax term ID comparisons.

    Term IDs are sometimes provided as strings. This is particularly evident in `wp_dropdown_categories()`, where the `selected` argument was not being respected. Plugin authors should also be wary of using strict comparisons for term IDs.

    Props booneistheman.
    Fixes #13237.
    ```

## 󠀁[Automatically Pre-fill Commit Message](https://make.wordpress.org/core/handbook/best-practices/commit-messages/?output_format=md#automatically-pre-fill-commit-message)󠁿

If you use Git (and possibly commit with git-svn), you can have a hook automatically
fill a new commit message with the standard format.

Create a `.git/hooks/prepare-commit-msg` file with the following script, and then`
chmod +x .git/hooks/prepare-commit-msg`.

    ```bash
    #!/bin/bash
    COMMIT_MSG_FILE=$1
    COMMIT_SOURCE=$2

    if [ $COMMIT_SOURCE ]; then
    	# A messages is already being provided via `commit -m`, rebase, etc.
    	exit 0;
    fi

    template="Component: Brief summary.

    Longer description with more details, such as a \`new_hook\` being introduced with the context of a \`\$post\` and a \`\$screen\`.

    More paragraphs can be added as needed.

    Props person, another.
    Fixes #30000. See #20202, #105.
    #
    # See https://make.wordpress.org/core/handbook/best-practices/commit-messages/ for more detailed guidelines."

    # Wrapping the variable in quotes preserves the newlines, because BASH is weird.
    echo "$template" > $COMMIT_MSG_FILE
    ```

## 󠀁[Other tips for committers](https://make.wordpress.org/core/handbook/best-practices/commit-messages/?output_format=md#other-tips-for-committers)󠁿

While these are not about the commit message itself, the following guidelines are
good to keep in mind.

During the RCrelease candidate One of the final stages in the version release cycle,
this version signals the potential to be a final release to the public. Also see
[alpha (beta)](https://make.wordpress.org/core/handbook/best-practices/commit-messages/?output_format=md#alpha-beta).
stage, [all patches must be reviewed by a second committer](https://make.wordpress.org/core/handbook/about/release-cycle/releasing-major-versions/#release-candidate)
before being committed.

### 󠀁[Before a commit](https://make.wordpress.org/core/handbook/best-practices/commit-messages/?output_format=md#before-a-commit)󠁿

 * If you have any doubts about whether or not a patch is acceptable, ask a few 
   other committers for a second opinion.
 * Make sure the changed lines conform to [the coding standards](https://make.wordpress.org/core/handbook/best-practices/coding-standards/):
    - PHPPHP The web scripting language in which WordPress is primarily architected.
      WordPress requires PHP 7.4 or higher
       * To run the full linter, run `composer run lint:errors`
       * To check all lines in all changed files, run `phpcs $(git diff trunk --
         name-only)` or `phpcs $(svn stat | grep "\(M \|A \)" | grep -v "external
         item" | cut -c8-)` .
       * Creating Bash aliases for the above commands is recommended for convenience.
    - JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming
      language commonly used to create interactive effects within web browsers. 
      WordPress makes extensive use of JS for a better user experience. While PHP
      is executed on the server, JS executes within a user’s browser. [https://www.javascript.com](https://www.javascript.com/)
       * [Run](https://make.wordpress.org/core/handbook/best-practices/coding-standards/javascript/#jshint)`
         npm run grunt jshint`. This will be done automatically by `npm run grunt
         precommit` as well.
    - HTMLHTML HyperText Markup Language. The semantic scripting language primarily
      used for outputting content in web browsers., CSSCSS Cascading Style Sheets.,
      a11yAccessibility Accessibility (commonly shortened to a11y) refers to the
      design of products, devices, services, or environments for people with disabilities.
      The concept of accessible design ensures both “direct access” (i.e. unassisted)
      and “indirect access” meaning compatibility with a person’s assistive technology(
      for example, computer screen readers). (https://en.wikipedia.org/wiki/Accessibility)
       * These must be checked manually.
 * Run `composer update`.
    - This ensures that the latest Composer dependencies are installed, which is
      particularly important for `composer/ca-bundle` which affects the built security
      certificate bundle.
 * Run `npm run grunt build && npm run grunt precommit`.
    - This runs the automated test suites for PHP and JavaScript, as well as various
      other tasks for CSS, images, etc.
    - You may also need to manually run PHPUnit with various flags, depending on
      the change.
 * Check the full diff one last time (`svn diff`). If you’re using Git, interactive
   staging (`git add -p`) is a good way to review individual chunks.
 * Check the list of modified files (`svn stat`), making sure that new files are
   added. It is also good to double check the contents of new files, as applying
   patches that add new files can result in the content of new files being duplicated.
   Also make sure that new files are not named the same as something in the  `$_old_files`
   array, or else they will be deleted again right away. If one is, comment out 
   the line from the array with a note indicating when a file with the same name
   was added back. Do not delete the line.
 * If deleting files that are present in the distributed WordPress build, add them
   to the `$_old_files` array.
 * You can “cherry-pick” commits from `trunk` to a release branch via `svn switch
   ^/branches/4.3 && svn merge -c 12345 ^/trunk`. You will be prompted to edit the
   message prior to committing. See [Backporting Commits](https://make.wordpress.org/core/handbook/best-practices/backporting-commits/)
   for more details.
 * Instructions for tagging and branching a release can be found in the [Core section of the releasing major versions](https://make.wordpress.org/core/handbook/about/release-cycle/releasing-major-versions/#core)
   page.
 * Bonus: for viewing modified files without including untracked files, add this
   as a Bash alias or function: `svn stat --ignore-externals | grep '^[^?X]'`

### 󠀁[After a commit](https://make.wordpress.org/core/handbook/best-practices/commit-messages/?output_format=md#after-a-commit)󠁿

 * Monitor the corresponding job in [GitHub Actions](https://github.com/WordPress/wordpress-develop/actions),
   in case any tests fail in other environments.

## 󠀁[More resources](https://make.wordpress.org/core/handbook/best-practices/commit-messages/?output_format=md#more-resources)󠁿

 * [A Note About Git Commit Messages](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
 * [5 Useful Tips For A Better Commit Message](https://robots.thoughtbot.com/5-useful-tips-for-a-better-commit-message)
 * [How to Write a Git Commit Message](http://chris.beams.io/posts/git-commit/)

First published

September 4, 2015

Last updated

August 17, 2026

## One response to “Commit Messages”

 1. ![Ella Iseulde Van Dorpe Avatar](https://secure.gravatar.com/avatar/603a3c8128c0966d4671b093c07634cf9f0f505644b82bfa5dcf57c27e5ded66?
    s=40&d=mm&r=g)
 2. [Ella Iseulde Van Dorpe](https://profiles.wordpress.org/ellatrix/)
 3. [September 29, 2015](https://make.wordpress.org/core/handbook/best-practices/commit-messages/#comment-27892)
 4. Should the “brief summary” or title have a period? I’ve always thought of it as
    a title, and omitting it makes it shorter too.

[  Previous: Writing Patches](https://make.wordpress.org/core/handbook/best-practices/writing-patches/)

[  Next: Backporting Commits](https://make.wordpress.org/core/handbook/best-practices/backporting-commits/)