We are developing software here, that will hopefully still be used in several months if not years and will also be need maintenance (by us). Therefore we should make it as easy to maintain in the future which means to make it as transparent as possible why certain changes were made in the past and what their intended consequences were. To this end, we should take the time and effort to make sure that the history of our project is as readable as possible. I believe this time and effort is a valuable investment and will pay off in the future.
Commit Content
Each commit should be atomic, i.e., one commit should contain exactly one logical change This make it easier to review, possible revert and is more helpful when reviewing the history.
Do not mix functional and cosmetic changes in one commit.
Branching
Before merging a commit make sure it has been rebased onto the master branch. Always merge with an explicit merge commit, do not fast-forward merges (this is the default behaviour in most web based git hosting platforms anyway).
This makes the history much more readable and should result in a history looking like below:
| Merge Commit |
|| || |/ | Merge Commit |
|/ | Merge Commit |
|| || |/ | Merge Commit
Commit Messages
Form
The first line of your commit message should summarize the commit message (executive summary) The first line should be separated by one empty line from the body of the commit message. The first line should not be longer than 50 characters, the body should not be longer than 72 characters (Other wise git log will be f*cked up.).
The summary should be in imperative form and should complete the sentence “If applied, this commit will “
Content of Commit Messages
Your commit message should answer:
- why you made these changes
Conventional Commits
We might want to use “Conventional Commits” https://www.conventionalcommits.org/en/v1.0.0/
Reading List
Some random links I found on the first page when google for “How to write good git commit messages” which all makes similar points: https://cbea.ms/git-commit/ https://wiki.openstack.org/wiki/GitCommitMessages https://gist.github.com/robertpainsi/b632364184e70900af4ab688decf6f53
