ROSE  0.11.96.11
Writing Git commit messages

What constitutes a good Git commit message.

Each commit should ideally provide a single bug fix or (part of) a feature, and thus the comment should be quite focused. Each commit message consists of a title line and a body separated from one another by a blank line.

Titles

Subjects are created on the fly. Their purpose is to make it easier for a human to scan a long list of commit titles to find certain things since it's faster to read a one or two word subject than it is to read a whole title. They also make it easier to visually group related commit titles. A few example subjects:

Subject nameWhat it means
Frontend, Binary AnalysisSome broad part of the ROSE library.
codethorn, compass2A particular project that uses ROSE.
Attribute, Stack DeltaSome specific feature.

Some examples of good commit titles:

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 body must be separated from the title by a blank line because some Git tools concatenate the first lines together into a single title line, which creates formatting problems since the title then becomes very long. Also, although ROSE uses a 130-column policy throughout, commit messages should try to keep lines around 80-characters because that works better in GUIs like github and qgit.

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.

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
   
   SymbolicExpr::TreeNode         -> SymbolicExpr::Node
   SymbolicExpr::TreeNodePtr      -> SymbolicExpr::Ptr
   SymbolicExpr::LeafNodePtr      -> SymbolicExpr::LeafPtr
   SymbolicExpr::InternalNodePtr  -> SymbolicExpr::InternalPtr

   BINARY-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.

   ROSE-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

JIRA Issues

To search for which commits implement a certain JIRA issue, use this command:

git log --grep '^ROSE-1234'

In a shell script, to get the list of all the JIRA issues for a particular commit, use this command:

git log -n1 --format='%B' $commit_sha1 |grep '^[A-Z]\+-[1-9][0-9]*$'
Collaboration diagram for Writing Git commit messages: