This document describes how to write good, useful commit messages.
The script that checks the policies stated here is called good-commits.pl in the ROSE "scripts" directory, and its usage is described below.
Titles
- The title must start with a parenthesized category not more than 20 characters.
- Titles must be short, single-line statements not more than 80 characters; details should go in the body.
- The title and body must be separated by a single blank line.
The parenthesized category is one or more words. The category's purpose is to make it easier for humans to quickly scan a long list of commits and see what they concern. The category names can be made up on the fly. Here are some examples:
| Examples | What they might mean |
| Frontend, Binary Analysis | Some broad part of the ROSE library. |
| codethorn, compass2 | A particular project that uses ROSE. |
| Attribute, Stack Delta | Some specific feature. |
The titles are intentionally short, but not as short as some best practices recommend. Some reasons for such short titles are:
- Tools and websites (e.g., Github, GitLab, qgit, Magit) have limited space in which to show a title and sometimes truncate the title if it's too long.
- When looking at long lists of commit titles, it's easier to read them if they're terse. Additional details can always be added to the commit message body.
Some examples of good titles:
- (Attributes) BinaryAnalysis::Attribute is moved
- (move tool) one more test case for comments handling
- (C++11) Minor fixes to compile ROSE with C++11
- (Tutorial) Fixed link error in tutorial
Body
The body provides details that are missing from the title and which are not easily evident from the patch. Some examples about what is good for a commit message body:
- The general overview of what changed. Often the patch is so detailed and/or spread out that it's hard to otherwise discern what really changed. For instance, if test answers are updated the commit should explain why the answer changed.
- Warning to the user if a ROSE API changed in a way that is not backward compatible.
- Where the commit came from, if not from the committer. For instance, if the commit was a patch submitted by a user it is polite to thank the user or the organization (provided they don't object).
- If controversial, the commit should mention its provenance. Perhaps it came from developer consensus at a team meeting. Otherwise someone who wasn't privy to that information might revert the commit later.
- Changes that affect users should be listed including what the user needs to change in their own code. Some of our users know how to use Git and will either look through the commit messages before merging or will search the commit messages when they have a compile error due to changed names. (On a similar note, try not to change the API without first using ROSE_DEPRECATED for a suitable period of time.)
- The body of the commit can be formatted as Markdown, which is readable to humans and can be displayed reasonably in user interfaces. The most useful Markdown in commit messages are: bullet lists introduced with asterisks, inline source code quoted in backticks, and multi-line source code delimited by lines containing three backticks.
Make sure your message is spelled correctly since it cannot be changed once it's merged into a release branch–at least not without a very disruptive history rewrite. Commit messages are for posterity, so be careful. "I hate git", commit a53823f, was unprofessional but is now effectively permanent.
Issue references
Every commit must reference at least one issue, and may reference multiple issues. The issues are listed after the message body and are separated from the body by a blank line. Issues are listed one per line. Each issue line has one of two forms:
- An all-uppercase word followed by a hyphen, followed by decimal digits.
- The word "Issue" followed by a space, the number sign (#), decimal digits, and an optional plus sign.
- The name of a Gitlab project followed immediately (no space) by the number sign, decimal digits, and an optional plus sign.
Some examples of issue references:
| Example | What it means |
| Issue #123 | An issue in the ROSE Gitlab project at rosecompiler2.llnl.gov/gitlab. |
| Issue #123+ | Similar, but will expand to the issue title when viewed in Gitlab. |
| ROSE#123+ | An issue in the ROSE project changed to a reference by Gitlab. |
| RC-123 | An issue in the ROSE Confluence instance. |
| JIRA-123 | Issue number 123 in JIRA, which the ROSE team no longer uses. |
The purpose of issue references in commit messages is to provide context and help trace the history of changes. For instance, in Gitlab it's easy for developers to hold a lengthy discussion about an issue, but it's not as easy to change a commit message.
To search for commits that implement a certain issue, use a command like this:
Commit message policy checker
The good-commits.pl script in ROSE's "scripts" directory checks that commits follow the policy outlined here. It should be run from inside the ROSE repository.
When run with no arguments it will show one line per commit over the last 30 days for the current user and indicate whether the commit passes the policy checks, or why it fails.
To create a summary table with one row per author, run the script with the "--histogram" switch plus any additional commit-selecting switches that are passed to the git rev-list command. For instance, the table that we create for the weekly ROSE meetings is generated by running:
Examples of good commit messages
This commit message makes it clear what users must change in their code:
(Binary Analysis) Changed names for some classes in the new SymbolicExpr **API CHANGE** SymbolicExpr::TreeNode -> SymbolicExpr::Node SymbolicExpr::TreeNodePtr -> SymbolicExpr::Ptr SymbolicExpr::LeafNodePtr -> SymbolicExpr::LeafPtr SymbolicExpr::InternalNodePtr -> SymbolicExpr::InternalPtr Issue #123
This commit makes it clear to the simulator2 project maintainer why a change was made since it was changed by someone that doesn't normally work on that project:
(Simulator2) Add Linux conditional around statfs::f_flags `statfs::f_flags` is only available since Linux 2.6.36. Our internal RHEL5 testing servers are Linux 2.6.18. RC-123
This commit explains why a change was made, which is not evident from the change itself:
(Git) Update .gitmodules to point to release repositories
This decision was reached during a team meeting with Dan,
Markus, Leo, Justin, and Pei-Hung.
The solution:
1. Merge the rose/scratch/edg.git branches into the
rose/edg4x/edg.git repository.
2. Update .gitmodules to point to the rose/edg4x/edg.git
release repository.
3. Remove the rose/scratch/edg.git repository once it
has been entirely merged into the rose/edg4x/edg.git
repository.
ROSE-123
JENKINS-456
