Skip to content

Convention for commit messages

Jump to bottom
Kelli Johnson edited this page Mar 25, 2021 · 3 revisions

Overview

Commit best practices based on Angular and Ishan Makadia . The following example shows how to create a well-formed commit message, where text inside <> refers to something you will type, e.g., text in the guidance below that looks like this <typethis>(<yes>) would look like typethis(yes) in your text editor, command window, or weapon of choice. And <BLANK LINE> means enter a manual carriage return. So, the resulting best-practice commit would be

Best practice

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

Details

Each of the following bullet points breaks down a single line in the best-practice example from top to bottom.

  • <type>(<scope>): <subject>
    • <type> is mandatory and can be any one of the following strings of text listed below and the information after the colon explains when it should be used.
      • build: changes that affect the build
      • chore: a code change that external user won't see (e.g., change to .gitignore file)
      • docs: documentation changes
      • feat: a new feature
      • fix: a bug fix
      • perf: code performance changes
      • refactor: changes to the code base that don't fix a bug or add a feature
      • style: stylistic changes to the code
      • test: changes or additions to tests
    • <scope> is optional and it seems natural to place the name of the function that the change pertains to here or the context that dictated why the change was made, e.g., CRANv1.0.0 or hotfix1.0.2. Essentially the scope helps people search issues, so think of one or two words that will help the future you find this issue when it is closed or you need to update your NEWS feed.
      • myfunction: the function name that the change pertains to
      • version: the version that you are working on
      • hotfix2: the fix that you are currently working on
    • <subject> is a succinct (<50 characters) description of the change that starts with a lower-case letter and does not end in a full stop.
  • <BLANK LINE>
  • <Body> Include information on the motivation for the change and contrast the change with previous behavior in less than 80 characters per line but use as many lines as you want. Consider using * to insert bullet points.
  • <BLANK LINE>
  • <Footer> Include information about breaking previous commits and GitHub issues that are closed by the commit using #<[0-9]+ for the issue number. You could also reference people here using @<githubname> if you wish for someone to comment on your commit or be notified of the changes. Limit footer lines to 80 characters per line.

Further notes

  • Do not be afraid to include a lot of information for the future you or for other followers of the code in the Body section. Only the first 60 or so characters of the top row will be visible on github or when you use git log --oneline in the command window, so don't feel like you are cluttering things by making a long commit message. Verbosity is good here!
  • I have found excellent examples of commit messages on Dev.
  • Use present tense, e.g., add, not past tense, e.g., added.
  • Feel free to edit this Wiki if you have more guidance.

References

Clone this wiki locally