Writing a commit message

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>

Additionally:

• The subject line should be no longer than 72 characters. Lines in the description should be no longer than 80 characters.
• Always use imperative mood for commit messages, 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).

Some examples of bad commit messages (Using a fictional I2C library as an example):

commit a6e149dfea1c8288714c90cbb26fed78022bac3b
Author: John Smith <[email protected]>
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

Specific mistakes

• 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 you change is doing.

  commit 41fdaf8df10cd6d16b96535b206b28c63345ef37 Author: Jane Doe [email protected] Date: Thu Dec 19 15:28:02 1991 +0000

    update README
  

  commit f5be8a027b42b4e238413f53ae1760eded2b2424 Author: John Smith [email protected] Date: Apr 2 23:16:08 1991 +0000

    LIBRARY VERSION UPDATE COMMIT
  

  commit 28c63344f10cd6d16b96535b206b28c63345ef37 Author: Jane Doe [email protected] Date: Thu Dec 19 09:28:00 1991 +0000

    fix for bug #334
  
    this change fixes all the problems from issue #334
  

  commit 53ae8a027b42b4e238413f53ae1760eded2b2424 Author: John Smith [email protected] 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)
  

Some examples of good commit messages (Using the same fictional I2C library):

commit a6e149dfea1c8288714c90cbb26fed78022bac3b
Author: John Smith <[email protected]>
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



commit 41fdaf8df10cd6d16b96535b206b28c63345ef37
Author: Jane Doe <[email protected]>
Date:   Thu Dec 19 15:28:02 1991 +0000

    lib/docs/README.md: add instructions to build I2C sample code



commit f5be8a027b42b4e238413f53ae1760eded2b2424
Author: John Smith <[email protected]>
Date:    Apr 2 23:16:08 1991 +0000

    Update version.txt to 8.0.0



commit 28c63344f10cd6d16b96535b206b28c63345ef37
Author: Jane Doe <[email protected]>
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".



commit 53ae8a027b42b4e238413f53ae1760eded2b2424
Author: John Smith <[email protected]>
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 <[email protected]>
Date:    Apr 2 12:12:11 1991 +0000

   lib/I2C/I2C.h: remove unused value from i2c_cfg struct (#229)

Add documentation URLs to I2C library README file

Upgrade I2C library version number to 0.5

I2C.h: Remove unused value in i2c_controller struct