-
Notifications
You must be signed in to change notification settings - Fork 142
Commit message rules
Bartosz Gentkowski edited this page Feb 6, 2018
·
5 revisions
To keep the history of the nrfx project clear and consistent for current and future developers, the following commit message rules are introduced.
Keeping commit messages clear and consistent helps to browse and understand history.
It also prevents the contributors from committing pointless changes because each commit must
adhere to the established set of rules.
- Each commit should contain one logical change. What is a logical change?
For example, adding a new feature or fixing a specific bug. Usually, if you cannot describe the change
in just a few words, it is too complex for a single commit.
To create a commit with a logical change, use the
git add -pcommand. - A good commit message should answer three questions
(http://who-t.blogspot.co.at/2009/12/on-commit-messages.html) :
- Why is it necessary? It may fix a bug, it may add a feature, it may improve performance, reliabilty, stability, or just be a change for the sake of correctness.
- How does it address the issue? For short obvious patches, this part can be omitted, but it should be a high level description of what the approach was.
- What effects does the patch have? In addition to the obvious ones, this may include benchmarks, side effects, and similar.
- A commit message should contain a short subject message, one blank line, and
multiple paragraphs describing the change. More details can be found at:
https://chris.beams.io/posts/git-commit/#seven-rules .
-
Short subject message - short description, subject, topic of done work written in
imperative mood (spoken or written as if giving a command or instruction). Start it with
the
EXT:prefix. Examples of good commit messages (https://chris.beams.io/posts/git-commit/#imperative):- https://github.com/spring-projects/spring-framework/commits/5ba3db?author=philwebb
- EXT: Refactor SPI driver for readability
- EXT: Add support for pca10040 board
- EXT: Remove deprecated functions from SPI driver
- EXT: Update SPI driver documentation
- EXT: Add multiple transfer functionality to SPI driver
- One blank line - a blank line to separate the topic of a commit from its body.
- Multiple paragraphs describing the change - The body, main description of the commit. Explanation of what has been changed in the code and why. Lines should be wrapped to 72 characters.
-
Short subject message - short description, subject, topic of done work written in
imperative mood (spoken or written as if giving a command or instruction). Start it with
the
Example of a good commit message, according to the above rules. This example is a nonsense commit, but shows how to properly construct a good and clear commit message:
EXT: Remove deprecated functions from SPI driver
Remove nrf_drv_spi_xfer, nrf_drv_spi_start_task_get,
nrf_drv_spi_end_event_get functions and related static functions.
nrf_drv_spi_transfer function must be used instead of
nrf_drv_spi_xfer. nrf_drv_spi_xfer was removed according to decision
to not support legacy API.
nrf_drv_spi_start_task_get and nrf_drv_spi_end_event_get
functionalities were moved to nrf_drv_common module to support more
generic API and are not supported in this version.
Side effect of these changes is speeding up interrupt handlers
when using two serial peripherals. Benchmark results are the following:
- Two peripherals, 8 B, xfer function code - 250 us
- Two peripherals, 8 B, transter function code - 190 us
Remember to keep the changelog file up to date!