Versions Compared

Old Version 6

changes.mady.by.user Christoph Meier

Saved on

compared with

New Version Current

changes.mady.by.user Mikaël Geljić

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

This page describes how to phrase reasonable Writing reasonable git commit messages . We assume that you have already read and agreed in Commit rules!

...

Reasonable commit messages facilitate:

...

helps fellow team members to read and understand a project's development history at a glance.

And there are many other good reasons to write reasonable git commit messages

Following this facilitates several other activities, such as documentation, root-cause analysis or reverting changes.

Example

Subject

Body

MAGNOLIA-6223 Add improved API for resource change observation

- Introduce ResourceChangeHandler and ResourceOriginChange classes
- Deprecate ResourceOrigin#watchForChanges(...) API and add registerResourceChangeHandler API
- Provide protected method for lazy initialisation of underlying resource change monitoring mechanism
- Implement basic support in AbstractResourceOrigin and provide an adaptor of old API to the new one there

General rule

As compiled by Chris Beams here and listed below, we follow the seven rules of a great git commit message. "Keep in mind: This has all been said before."

TL;DR

  1. Separate subject from body with a blank line
  2. Limit the subject line to 50 characters
  3. Capitalize the subject line
  4. Do not end the subject line with a period
  5. Use the imperative mood in the subject line
  6. Wrap the body at 72 characters
  7. Use the body to explain what and why vs. how

On top of these rules, mind the following Magnolia-specific guidelines:

Tip
  • The subject should start with the Jira ticket number, in the appropriate Jira project corresponding to the repository at hand.
  • All code changes must belong to a Jira ticket, even if they are "only" considered refactoring. If a ticket does not exist in the current project, please create it and link it as appropriate.
  • Please avoid cross-referencing Jira projects from other repositories. This makes it hard to track changes, know when a module should be released, or which ticket/version introduced or fixed an issue.
  • Commits only updating internal versions in webapps/bundles may use the motivating Jira ticket from that module, or simply no prefix at all, e.g. "Bump personalization to 2.1-SNAPSHOT".
  • QA prefix may be used, but exclusively for 100% cosmetic changes, e.g. formatting, Javadoc.
  • Make sure the subject describes and summarizes well what you have done with the commit. The title/issue summary in Jira may be a good starting point, however do not just copy paste!

Table of Contents

Intro

Image Removed

Below you will find seven good rules to write great commit messages. But before, please remember this specific Magnolia rule(s)

Note

The subject  of the commit message MUST start with either

  • JIRA ticket number or
  • QA

To start the message with QA is a rare case. Typical examples for QA commits are:

  • Raising version number of the project (for instance in a bundle pom)
  • Formatting
  • Javadoc improvments
Do not commit code changes with QA! even if it is refactoring.

The seven rules of a great git commit message

1. Separate subject from body with a blank line

From the git commit manpage:

...

There are a number of other contexts in git where the distinction between subject line and body kicks in—but none of them work properly without the blank line in between.


2. Limit the subject line to 50 characters

Note

The advice to limit the subject line to 50 characters is well-intentioned - it seems very hard to follow. Check the git log of main, ui and other Magnolia projects and try to find commit message subjects which use not more than 50 characters.

To keep the commit message subject clean and short is very important, but very often it seems impossible to follow the "50 characters rule".

If you can manage not to use more than 72 (see rule #6) - seems fine.

(Personal note from Christoph Meier)


50 characters is not a hard limit, just a rule of thumb. Keeping subject lines at this length ensures that they are readable, and forces the author to think for a moment about the most concise way to explain what's going on.

...

So shoot for 50 characters, but consider 69 the hard limit.


3. Capitalize the subject line

This is as simple as it sounds. Begin all subject lines with a capital letter.

...

  • accelerate to 88 miles per hour


4. Do not end the subject line with a period

Trailing punctuation is unnecessary in subject lines. Besides, space is precious when you're trying to keep them to 50 chars or less.

...

Instead of:

  • Open the pod bay doors.


5. Use the imperative mood in the subject line

Imperative mood just means "spoken or written as if giving a command or instruction". A few examples:

...

Remember: Use of the imperative is important only in the subject line. You can relax this restriction when you're writing the body.


6. Wrap the body at 72 characters

Git never wraps text automatically. When you write the body of a commit message, you must mind its right margin, and wrap text manually.

...

A good text editor can help here. It's easy to configure Vim, for example, to wrap text at 72 characters when you're writing a git commit. Traditionally, however, IDEs have been terrible at providing smart support for text wrapping in commit messages (although in recent versions, IntelliJ IDEA has finally gotten better about this).


7. Use the body to explain what and why vs. how

This commit from Bitcoin Core is a great example of explaining what changed and why:

...

In most cases, you can leave out details about how a change has been made. Code is generally self-explanatory in this regard (and if the code is so complex that it needs to be explained in prose, that's what source comments are for). Just focus on making clear the reasons you made the change in the first place—the way things worked before the change (and what was wrong with that), the way they work now, and why you decided to solve it the way you did.

References

http://chris.beams.io/posts/git-commit/