Commit Notes

Commit Message Convention

A commit message basically consists of 2 parts: subject and body.

Subject (or title) is a concise summary in a single line. It should clearly state what you have done and it may state why you have done something.

Body part is optional. It contains some additional information or details about the commit. It can be several lines.

Commit Message Template

<subject_in_a_single_line>
<single_blank_line>
<optional_multiline_body_part>
<single_blank_line>
<optional_issue_fix_line>

Here are the things to remember while writing a commit message for a coherent commit (message) history:

• Use imperative present tense. (e.g. Add support for location instead of Added support for location or Adds support for location)
• Capitalize each line.
• Do not end subject line with a dot (.).
• Leave a single empty line between the subject and the body parts.
• If the commit solves some Issues, write Fix #<IssueID1>, Fix #<IssueID2>, ... in <optional_issue_fix_line>. (See Closing Issues via Commit Messages)
• If the body part mentions about several actions, prefer to list those actions (an action at a line) using *.
• Use following keywords as appropriate:
  • Create to state that you created some new files or directories. (e.g. Create 'docs' directory to store non-project files)
  • Update to state that you updated the content of some files. (e.g. Update my_file.txt for this reason)
  • Rename to state that you renamed some files or directories. (e.g. Rename old_file_name.cpp to new_file_name.cpp
  • Delete to state that you deleted some files or directories. (e.g. Delete 'temp' directory and all the files in it)
  • Add to state that you added some new sections to some files. (e.g. Add 'Project Description' section to README.md)
  • Add to state that you added some new features/functionalities to the project. (e.g. Add support for location to memory posts)
  • Add to state that you added some existing files. (e.g. Add README.md)
  • Implement to state you implemented some new code. (e.g. Implement method 'findGeoCoordinates' in location.cpp)
  • Revise to state that you reimplemented some existing code. (e.g. Revise 'findGeoCoordinates' method for better performance)
  • Fix to state that you fixed some bugs/errors in some existing code. (e.g. Fix string concatenation error in 'findGeoCoordinates' method)
  • Format to state that you reformatted the text of some files (no functionality change). (e.g. Format my_file.java and add some blank lines for readability)
• If your commit contains different types of actions, state the most important ones in subject line and the others in the body part. Also, don't state the actions that are implicitly implied by other ones. (See the following example scenario.)

An Example Commit Scenario

Suppose there is an Issue with ID 8 which is about adding location support to memory items. Suppose you implemented a method/function named findLocation in the existing file post.py to add support for location to memory posts. In this scenario implementing the method implicitly implies that the post.py is updated. So, there is no need to write Update post.py. The important action here is adding the support for location. Implementing some code is the detail of this action. So, corresponding commit message should be something like:

Add support for location to memory posts.

* Implement 'findLocation' method in post.py using Google GeoCode service.
* Integrate that method with Post models.

Fix #8

Note the empty lines after the subject line and before Fix #8.

---

Closing Issues via Commit Messages

Including one of the following keywords with #<issue_id> in a commit message (either in the title or the description) will automatically close the issue when the commit is merged into the default branch (which is master in our repo).

• close, closes, closed
• fix, fixes, fixed
• resolve, resolves, resolved

Some examples from here:

A commit message with Fixes #45 will close issue 45 in that repository once the commit is merged into the default branch.

To close multiple issues, preface each issue reference with one of the above keywords. You must use the keyword before each issue you reference for the keyword to work. For example, This closes #34, closes #23, and closes #42 would close issues #34, #23 and #42 in the repository.

It is important to close Issues that are related to the project via commit messages instead of closing them by hand. Consider the following example scenario:

• An Issue (say #8) is opened (with label status:not-started) which states that there is a bug in some part of the project.
• The assignee creates a new branch (say B) (or checks out to an existing branch other than master) to work on the Issue. (And updates the Issue with label status:in-progress to tell that the Issue is being worked on.)
• Here are 2 different paths:
  1. The assignee fixes the bug in branch B and pushes changes to the central repository (to branch B). Then, (s)he updates the Issue with label status:completed to tell that the Issue is solved. Then, closes the Issue by hand.
  2. The assignee fixes the bug in branch B, adds a commit message containing Fix #8 and pushes changes to the central repository. Then, (s)he updates the Issue with label status:completed to tell that the Issue is solved.
• In path (i), people will assume that the current master branch is bug-free since they see Issue #8 as solved and closed. In fact, the fix to Issue #8 exists only in branch B, it is not in master branch yet.
• In path (ii), GitHub automatically adds a message to Issue #8 which states that the Issue has been solved in a commit (in branch B) and will be closed once that commit is merged into master branch. So, people will know that the current master branch does not contain the fix to Issue #8.

So, it is advised to follow path (ii) while dealing with the Issues that are related to the project.