Git commit rules

Following rules apply for "official" branches.

You can always use more "personal/temporary" branches to save your code and/or share code with your teammates before you go on vacation. On these "personal/temporary" branches, there is no specific rules.

In a nutshell

• A commit must not fail a build. Most important!
• Don't Commit Half-Done Work
  • A commit should be made of one logical unit of change - whether a single line/character or a whole file/class with corresponding changes in other parts of code, still following #1.
  • It shouldn't have any value if done partly
• What is a logical unit of change? In terms of git, if you can specify the changes in the commit message in least number of characters, in one sentence (without ANDs of-course), and you can not break that description further into smaller units, that I call one unit.
• It shouldn't contain a lot of diff noise (whitespace and style changes, unless the commit is specific for that)
  • use separate commit for code reformatting (see below)
• A commit must always be linked to an issue (except cases in following item)
• Use separate commit with no associated Issue for:
  • Code reformatting
  • Remove dead code
  • Fix typo
• Commit message respect the pattern described in the next chapter

Example

Issue https://github.com/TypeCobolTeam/TypeCobol/issues/893 was about 2 rules. The developer made 2 separated commits for each rules. A few weeks later, 1 rule was obsolete. As there was a dedicated commit for each rule, we just had to revert the commit. If only commit was made for the 2 rules, it would have been more complicated.

How to write commit messages

• Use the message to explain what and why vs. how
• Never start a line with # because these lines will be interpreted as comment by some git command (like rebase)
• Wrap each line of the message at 72 characters
  • Line break the commit message (to make the commit message readable without having to scroll horizontally in gitk).
• Use the imperative mood
  • Write the summary line and description of what you have done in the imperative mode, that is as if you were commanding someone. Start the line with "Fix", "Add", "Change" instead of "Fixed", "Added", "Changed".

Pattern of a commit message

GitHubVerbOrWI #xxx Verb summary

Description (optional)

• Summary line(s):

  • GitHubVerbOrWI : If you want to automatically close the issue when your commit is pushed to the default branch of the repo. You can use of one this keyword : Close, Fix. Otherwise just use WI.
  • #xxx : Is the reference to an issue
  • Verb :
    • If you used Fix before, then skip Verb
    • Otherwise Use infinitive verbs like Add, Refactor, Merge, ... Instead of Added, Adding, Refactored, Merged.
  • Summary : description of the commit.
  • Do not end the title line with a period
  • Try to limit the summary line(s) to 80 characters. Any more elaboration should be part of the description.

• Next lines (optional):

  • If there is a description, the second line must be blank

Tips

• If it seems difficult to summarize what your commit does, it may be because it includes several logical changes or bug fixes, and are better split up into several commits using git add -p.
• if your file contains changes about different issues, use "git add -p" to split changes into separate commit

References

Git commit granularity

https://github.com/trein/dev-best-practices/wiki/Git-Commit-Best-Practices

http://gitforteams.com/resources/commit-granularity.html

https://sethrobertson.github.io/GitBestPractices/

https://homes.cs.washington.edu/~mernst/advice/version-control.html

How to write commit messages

https://chris.beams.io/posts/git-commit/

https://github.com/erlang/otp/wiki/writing-good-commit-messages