Title: Create a good commit message
Author: WordPress VIP Documentation
Published: March 10, 2026

---

 1. [Guidebooks](https://docs.wpvip.com/guidebooks/)
 2. [Developer best practices](https://docs.wpvip.com/guidebooks/developer-best-practices/)
 3. Create a good commit message

#  Create a good commit message

Commit messages are one of the most common ways that developers communicate with
each other. As part of the GitHub flow, it is important that commit messages are
informative and clearly written.

A well written commit message can save time and work in the long run by clearly 
communicating the intention of a commit. Commit messages are helpful to reviewers
in a pull request, but later they will also be useful to people who are debugging
code or reading a commit timeline.

## Write a topical subject line

Good commit messages should have a subject line that briefly describes the change
that was made and—when appropriate—why the change was necessary. A good subject 
line will enable a reader to understand the basic gist of a commit without needing
to read the entire commit message.

This example subject line mentions what was changed:

    ```wp-block-preformatted
    Add a custom post type
    ```

An improved version of the subject line answers the question “What kind of custom
post type?”:

    ```wp-block-preformatted
    Add a custom post type for portfolio content 
    ```

A further improved version of the subject line also answers the question “Why was
this custom post type needed?”:

    ```wp-block-preformatted
    Add a custom post type for portfolio content to have its own format and RSS feed
    ```

If the commit is a part of a clearly-defined and named project, prefixing the commit
with the project name can also be very helpful. For example:

    ```wp-block-preformatted
    Artist Theme Project: Add a custom post type for portfolio content to have its own format and RSS feed
    ```

If a subject line includes the word “and”—or in other way lists more than one item—
the commit is probably too large and should be split into more than one commit.

## Write an informative commit message

After the subject line, there should be an empty line before the rest of the commit
message for readability.

The commit message should clearly communicate what was changed, the intent or goal
of the change, and include details about complex abstractions. It is perfectly acceptable
to spend more time crafting a commit message than writing the code for a commit.
The length of the commit message might even be longer than the commit itself.

 * **Explain why a change was made: **Add a clear explanation for the change to 
   help a reader of the commit learn a new approach, or to help someone tracing 
   a bug to understand the context of the problem better. This can help determine
   if the root cause of a bug is in that commit or further up the chain.
 * **Explain the cause and consequences of the problem:** Knowing what caused a 
   problem can avoid causing a similar problem again and understanding the consequences
   can help explain any erroneous behavior. For instance, during debugging, one 
   can compare the consequences of a fixed problem with the new one.
 * **Explain how the commit achieves the goal:** On occasions where it’s unclear,
   explaining the _how_ benefits the reader (e.g. some high-level algorithm is encoded
   in the change) and highlights the importance of knowing it.

This example commit message provides the reader with an explanation of what was 
changed, why it was changed, and what goal was achieved:

    ```wp-block-preformatted
    Artist Theme Project: Add a custom post type for portfolio content to have its own format and RSS feedAdded a custom post type for portfolio content that has built-in custom fields for media, date, and price. The CPT also allows us to create an RSS feed by using core WordPress behavior rather than writing complicated code. 
    ```

GitHub will truncate any Pull Request title greater than 72 characters and replace
the remaining characters with an ellipses (`...`). If a Pull Request only has one
commit, GitHub will use the commit message as the Pull Request title, however the
Pull Request title can be modified when opening the Pull Request to ensure that 
it’s less than 72 characters.

[Read more about creating commits on GitHub](https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/about-commits)

Last updated: March 10, 2026

---

## Post navigation

 *  [ Previous GitHub flow on the VIP Platform ](https://docs.wpvip.com/guidebooks/developer-best-practices/github-flow-on-the-vip-platform/)
 *  [ Next Create a good changeset ](https://docs.wpvip.com/guidebooks/developer-best-practices/create-a-good-changeset/)