=================
Git Best Practice
=================

Commit Contents
===============

* Don't do multiple things in one commit, use multiple commits for that.
* Do commits as atomically as possible (or: as atomically as it still makes sense/is reasonable; giant commits as well as micro-commiting doesn't make any sense).
* Rule of thumb: each commit should be revertable as-is and by itself. Means: if you commit something and someone else needs to revert that commit, s/he should need to only revert that commit and not split it or edit anything else in order to do that.

Generally, the kernel.org documentation about `SubmittingPatches <http://www.kernel.org/doc/Documentation/SubmittingPatches>`_ is reasonable too.

Commit Messages
===============

Commit messages should consist of two parts:

* always use signed-off lines in commits and sign them with your PGP key ``git commit -a -s -S``.

* **one** sentence on the **first** line (doesn't matter how long/as many words as you want):
  
  * give a broad idea about *what* got changed and *why* it was changed (not a detailed of the *what* since that is visible in the diff).

* any additional/technical/in-depth details go into one or more paragraphs *after* the first sentence:

  * broader explenation(s) why something was done the way it was done (especially if it's not obvious or has a back history).
  * optionally some information who was involved/helped/debugged, links to further information etc.

* since git commits should be revertable by its own, you should have commit messages that are unique:

  * e.g. if you're updating copyright notices, don't use "Updating copyright notices." since this is a reoccuring task, use "Updating copyright notices for 2014." instead.