Commit message rules

Commit message rules

To keep history of the nrfx project clear and consistent for current and future developers, commit message rules are introduced.

Why?

Keeping commit messages clear and consistent helps to find and understand history. It is also not directly forcing to thinking during development and not commiting pointless changes.

The rules

• Commit should contain one logical change. Not two, three, five. One. What the logical change is? For example adding new feature or fixing specific bug. Is it is not possible to describe changes in few words, the change could be or rather is too complex for a single commit. To create commit with logical change git add -p can be helpful.
• 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, etc.)
• Commit message should contain short subject message, one blank line and multiple paragraphs describing 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). Please 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 - just blank line to separate topic of a commit from body, explanation.
  • Multiple paragraphs describing change - The body, main description of the commit. Explanation what in the code was changed and why it was done. Lines should be wrapped to 72 characters.

Example of good commit message (according to the rules). Remember it is not real case and is nonsense, but shows how to construct 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 has to 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 in cases
when using two serial peripherals. Benchmark is here:
 - Two peripherals, 8B, xfer function code - 250us
 - Two peripherals, 8B, transter function code - 190us

Finishing the task

Remember to keep changelog file up to date!