Writing a commit message
Erik Nyquist edited this page Jan 6, 2017
·
23 revisions
A good commit message should have two basic parts; a subject, and a description (if required). The subject is always on the first line (and only the first line), and the description is always separated from the subject with a blank line.
<Subject: brief one-liner describing your changes>
<Description: if more detail is needed, then skip a line
and put it in the description. However, if you don't think
you need it, then a one-line commit message is OK>
Additional rules:
- The subject line should be no longer than 72 characters. Lines in the description should be no longer than 80 characters.
- When describing changes to the code, always use imperative mood, as if you are commanding the code to change its behaviour; instead of saying "I added a new feature" and "I fixed the bug", say "Add a new feature" and "Fix the bug".
- Make sure your commit message contains an accurate summary of your changes (for example, "Made some improvements" is a bad commit message). If you're finding it difficult to summarise your changes in one short commit message, then perhaps you should consider breaking the change up into multiple commits, within reason (i.e. no broken commits-- every commit should compile and be functional).
Let's look at some bad commit messages, and re-write them to be better.
commit a6e149dfea1c8288714c90cbb26fed78022bac3b
Author: John Smith <john.smith@madeup.com>
Date: Sun Jan 6 01:04:46 1991 +0000
I2C library fixes
This fixes some of the recent errors that have been happening in the I2C library
- Subject line is too vague. The subject line needs to contain some specific details about the change, so that anyone looking at the git logs will get an accurate idea of what your change is doing, and why it is needed.
- The description has a line exceeding 80 characters in length. All lines in the description must contain no more than 80 characters.
- Not using imperative mood. Refer to Rule #2 above-- Don't say "I fixed the bug", say "fix the bug".
commit a6e149dfea1c8288714c90cbb26fed78022bac3b
Author: John Smith <john.smith@madeup.com>
Date: Sun Jan 6 01:04:46 1991 +0000
I2C.c: handle null pointer in i2c_getbytes()
Check that the provided pointer to i2c_err_callback is non-NULL
before attempting to execute it
- Subject line has a good summary, including source file name & function name
- Description provides some extra technical details
- The reason for the change is clear
- Imperative mood being used
commit 41fdaf8df10cd6d16b96535b206b28c63345ef37
Author: Jane Doe <jane.doe@fake.org>
Date: Thu Dec 19 15:28:02 1991 +0000
update README
- Again, the subject line is too vague. What is being added to the README, and why? we should be able to tell from the commit message.
commit 41fdaf8df10cd6d16b96535b206b28c63345ef37
Author: Jane Doe <jane.doe@fake.org>
Date: Thu Dec 19 15:28:02 1991 +0000
lib/docs/README.md: add instructions to build I2C sample code
This change was requested by user xyz on Github issue #123
- Subject line has a good summary with specific details
- The reason for the change is clear
commit f5be8a027b42b4e238413f53ae1760eded2b2424
Author: John Smith <john.smith@madeup.com>
Date: Apr 2 23:16:08 1991 +0000
LIBRARY VERSION UPDATE COMMIT
- All capitals; no need to shout!
- Specifying "commit" in the commit message; don't do that. We already know it's a commit, you don't need to tell us in the message!
- Subject line is too vague, needs more detail.
commit f5be8a027b42b4e238413f53ae1760eded2b2424
Author: John Smith <john.smith@madeup.com>
Date: Apr 2 23:16:08 1991 +0000
Update version.txt to 8.0.0
- Subject line has a good summary with specific details
- No needless capitalization
- No needless use of the word "commit"
commit 28c63344f10cd6d16b96535b206b28c63345ef37
Author: Jane Doe <jane.doe@fake.org>
Date: Thu Dec 19 09:28:00 1991 +0000
fix for bug #334
this change fixes all the problems from issue #334
- Subject line is too vague, needs specific details
- Description is also too vague, not enough details
- Not using imperative mood ("Fix the problem", not "This fixes the problem")
commit 28c63344f10cd6d16b96535b206b28c63345ef37
Author: Jane Doe <jane.doe@fake.org>
Date: Thu Dec 19 09:28:00 1991 +0000
I2C library: rename constants to avoid conflicts with SPI (#334)
Both SPI.h and I2C.h define a preprocessor symbol called "CLK_DIV_16".
Change I2C.c and I2C.h to use "I2C_CLK_DIV_16"
- Subject line has a good summary with specific details
- Description provides further details about the files & symbols affected
- Imperative mood is being used
commit 53ae8a027b42b4e238413f53ae1760eded2b2424
Author: John Smith <john.smith@madeup.com>
Date: Apr 2 12:11:11 1991 +0000
various fixes for I2C library: improve ISR performance (#256), remove unused value in i2c_controller struct (#229)
- Subject line is too long. The subject line must me no more than 72 characters
- Subject line is too vague, needs more detail
- Two unrelated changes in one commit. These should be separated into different commits.
####How can we write this message better?
commit 53ae8a027b42b4e238413f53ae1760eded2b2424
Author: John Smith <john.smith@madeup.com>
Date: Apr 2 12:11:11 1991 +0000
lib/I2C/I2C.c: don't call delay in the ISR (#256)
Delays should not be used in interrupt context. Remove all
delays from the I2C ISR, and re-write the ISR so that delays
are not required (issue #256).
commit 53ae8a027b42b4e238413f53ae1760eded2b2424
Author: John Smith <john.smith@madeup.com>
Date: Apr 2 12:12:11 1991 +0000
lib/I2C/I2C.h: remove unused value from i2c_cfg struct (#229)
####Why is this better?
- Two unrelated changes are now separated into different commits
- Each subject line is under 72 characters
- Each subject line has a good summary of the change, with specific details given
- The description has only lines under 80 characters
- The description provides further technical details about the problem & fix
- The reason for both commits is clear