README.commits

Commits are changes to the codebase, consisting of the code change itself and a
commit message. Creating a good commit is sometimes quite an art. This
guidelines should help you with it.

The most important rule for commits is quite simple:

       Value the time of your readers/reviewers much more than yours.

Everything else is mostly a corollary.

Code changes
------------

One commit should solve one problem. It should be an atomical unit -- before and
after the commit, the code should be in consistent state. If you can break the
problem into more subproblems, it is usually good idea to do it and split the
change into more commits. This makes the understanding and reviewing the commits
much easier. The important exceptions are:

 1. You are doing the same or very similar change on many places.

       2. You are rewriting a part of the code completely.

You can label related commits using the commit message (e.g. "Foo refactoring
1/3: Extracting methods").

Commit messages
---------------

The purpose of a commit message is:

 1. To describe a change in the code for other people and your own future self.

 2. To explain why it was done.

The first point usually isn't a problem, but the second can be tricky.

Commit messages describing the change well help tremendously when reviewing,
debugging, digging through history, etc. -- mainly because they allow separating
relevant changes from the irrelevant. When you need to look at the diff to
actually determine if the commit is relevant for you, the description is bad.

Good description does not need to be long -- for trivial changes like
formatting, description "Improve formatting" is adequate. But it should be
specific and contain relevant keywords so that grep in the commit log works
sanely.

Example:

       When porting test fixes from master to onsite_1_1 branch, grepping through the
       master's log for "fix tests" and similar phrases helped quite a lot to find
       the fixes. It wouldn't work if the descriptions were bad.

When you are making a change in the code, you are making it for some reason.
Sometimes the reason is simple and obvious (e.g. adding new functionality),
sometimes it is quite complicated (e.g. result of a lengthy discussion weighting
many factors or several hours of bug investigation). Whenever you make a change
for non-obvious reason and don't state the reason anywhere, you basically just
thrown the effort of coming to it out of the window.

Example:

       You spend the whole day hunting down a bug and add two lines of code as a
       result. But a year after someone will be rewriting that part of the program.
       If he won't understand from the "git blame" why the change was made, it is
       quite likely he'll just throw the code out as unnecessary -- which will cause
       a regression and probably another day lost by someone hunting the bug down
       again. And no, the rewriter will not ask you -- because at the time, you may
       be working on other project or company.

Code that nobody understands has no value. And the gap in understanding usually
isn't because one doesn't see what is happening in the code, but *why*. So,
please preserve information about your reasoning when doing a changes. It may be
in comments, commit messages, or bugs referenced from them -- that does not
matter much. It matters that the information is available. These two minutes
spent writing it down are spent well.

To reference bugs at bugzilla.novell.com, use the format bnc#123456.

To reference FATE entries at fate.novell.com, use the format fate#123456.

Examples of well-written commit messages:

 Example 1:

               work around ruby >= 1.8.7-p248 segfault bug #2781

               This seems to avoid triggering whatever craziness is causing
               the segfault. For more info see:

               http://redmine.ruby-lang.org/issues/show/2781

   (http://bit.ly/9MijD8)

       Example 2:

               Set X-Cascade header when using pass

               Setting X-Cascade: pass allows middleware outside the Sinatra stack
               to continue trying to match the request.

   (http://bit.ly/9aV9g3)

       Example 3:

               fix a weird integration issue.
               some processes run the
               provide/require processor after scope creation.  That means
               that TypedScopeCreator can't assign types to the
               new namespaces.  Normal closure compiler is moving towards a model
               where TypedScopeCreator declares namespaces in the global
               scope.
               It's not clear how we should resolve this inconsistency, but
               for now this shim will make things better.

       (http://code.google.com/p/closure-compiler/source/detail?r=419)

       Example 4:

               Attach types to literals at scope-creation time instead of at
               inference time.
               Scope-creation already attaches types to function literals at
               scope-creation type, so this makes the other literals more consistent
               with function literals.

               (http://code.google.com/p/closure-compiler/source/detail?r=411)

 Note that the first line usually describes the change, others
 explain the reasoning.

Git has some specific rules for formatting commit message that other version
systems don't have. If you break them, nothing fails, but if you adhere to them,
Git will work better for you and for others. They are nicely summarized e.g.
here:

 http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

Consider these rules part of these guidelines and use them as much as
practically possible.