In order to provide valuable and consistent commit messages in our project we use the “imperative present tense” style for commit messages and an operator to show the feature’s effect on the public API.

Write commit message as Fix bug and not Fixed bug or Fixes bug This convention matches commit messages generated by commands like git merge and git revert.

[ More info: tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html ]

In order to track the effects of changes onto the public API, explicitly classify every commit into exactly one of three categories:

Marker Category Description
= Neutral Only touches things “under the hood” and has no effect on the public API.
+ Extending Extends the API by adding things. In rare cases this might break code due to things like identifier shadowing but is generally considered a “safe” change.
! Breaking Changes or removes public API elements. Will definitely break user code relying on these parts of the API surface.
     

While working on a feature, you may then end up having many commits, such as:

+ component: add new foo field to the bar object
= test: tidy fixtures
= component: refactor code
+ component: add new foo field to the baz object
= component: update fixture
 

Merging these directly into master from a branch would be noisy, so from one branch and one PR, we should squash commits into one. Also, given we manage our issues in Jira and there is currently no link with Github, I propose we add the current ticket number into a major commit too. So the single commit in a PR would become:

+ PROJECT-999: add foo to the bar and baz JSON objects

All commits in the “Extending” and especially in the “Breaking” category should contain a dedicated paragraph (in addition to the summary line) explaining in what way the change breaks the API and why this is necessary/beneficial.