[racket-dev] Commit messages

There have been some bad commit messages recently, so here's some
general reminder/guidelines/whatever.  (Maybe someone would care to
rewrite this into something that can be put with the style guide?)
It's roughly adapted from the conventions from the git project.

0.1. This is all coming in addition to the usual things with the actual
     change: make sure that things compile, run the relevant tests,
     include tests and docs for the change, use good style, etc.

0.2. Also, try to minimize whitespace errors: try to avoid extra
     whitespace at end of lines (hard, I know, since drr doesn't
     remove them), avoid tab characters (easy with drr), and really
     avoid tabs that are not the first thing on the line.  Also,
     please make sure that files end with a newline -- it's also easy
     to forget this with drr, and it makes life hard with many textual
     tools.  You can use "git diff --check" to check whether you're
     introducing new whitepace errors.  (Note that some projects
     actually forbid all of these things using it.)

1. The most major thing to bear in mind with a commit message is the
   same thing that you should remember when you write the code: the
   purpose of the commit message is for other humans to read & review.

2. Make your commits a logical unit of change.  Commits like "toward
   X" are bad because of this.  Think of a reviewer for the changes,
   or trying to figure out how something was made, and it's obvious
   why those commits are bad.  On the other hand, a commit that does
   three unrelated things is bad too.

   Note that it's fine to have such commits in your own repository,
   but take the time to organize them later -- combine partial commits
   to a single one, split big commits to their parts, etc.  Don't be
   affraid to use git's history editing tools to do this work: the
   history on the main repository is immutable, so you're only
   organizing the new work that you're pushing.

   Obviously, splitting a commit is harder than combining commits, so
   it's better to have smaller commits in the first place.  If you
   have a bunch of changes in a single file that should go in separate
   commits, then you can use "git add -p" which will go over each hunk
   and ask you if you want to include it or not.  Better yet, there
   are tools that allow you to select which hunks to include in a
   commit (I use magit in Emacs which is really great for this).

3. Start the commit message with a short-one-line description of the
   commit.  Describe the code change, not what it was made for.  For
   example "Fix PR 123" or "Patch from Foo" are bad descriptions since
   they provide very little information for reviewing commits.  These
   short descriptions are used in many tools, and even in cases where
   you see the full commit, having a short subject line makes things
   much easier.

4. Usually there is no need to prefix the header with the component
   that you're changing.  The commit already has the files that are
   changed, and most git tools (including our notification emails)
   will show that list -- so a "[Honu]" prefix is redundant when all
   the changes are in "collects/honu/*".  This also means that in some
   cases a very short commit message is fine -- even something like
   "Typo" is clear given the file it is fixing.

   Note that this is different than other communications like mailing
   list posts, bug reports, and patch requests where the context does
   help and in many cases needed to clarify things.  So bear in mind
   that when you resolve a bug that starts with "[TR]" you don't need
   to do the same with the commit message.

5. In really short commits the short one-line can be enough, but in
   many cases, a more complete description of the change should
   follow -- the "body" of the commit message.

   Important: the one-line summary and the body should be separated by
   one empty line.  This is just how git (and related tools) work.
   Not having that empty line means that the whole text will be used
   as the short description.

6. The body should provide a meaningful commit message, which explains
   the problem the change tries to solve (what was wrong) and
   justifies the change the problem (how it is solved).  It's fine to
   include descriptions of possible alternatives, subtle reasons why
   you chose a particular strategy over another, etc.  Again, just
   think about someone reading over the change in two years and trying
   to figure out why you did what you did.

7. Describe changes in imperative mood, e.g., "make xyzzy do frotz"
   instead of "[This patch] makes xyzzy do frotz" or "[I] changed
   xyzzy to do frotz" or "adding xyzzy", as if you are giving orders
   to the codebase to change its behavior.

8. Try to make sure your explanation understandable without external
   resources like a URL to a blog post or a mailing list archive.
   It's ok to include them for reference, but it's better to summarize
   the relevant points of the discussion.  (IOW, bear in mind that the
   commit log is more robust than such resources.)

9. Do not check in commented out code or unneeded files -- it's safe
   to delete the code (that's what a code management system is for).

10. Avoid frequent changes to binary files (usually images).  These
    changes have a much bigger cost in terms of repository space,
    which ultimately means slower repository interactions for
    everyone.

-- 
          ((lambda (x) (x x)) (lambda (x) (x x)))          Eli Barzilay:
                    http://barzilay.org/                   Maze is Life!