Re: [PATCH v2 3/4] fast-export: don't handle uninteresting refs

From: Jonathan Nieder <jrnieder@gmail.com>
Date: Oct 31, 2012, 01:51 UTC
Message-ID: <20121031015103.GA15167@elie.Belkin>
In-Reply-To: <CAMP44s0RcbAiUmvGACxO+H-b-anQSPXxUqUuZwYRKWfrpXYeew@mail.gmail.com>

Felipe Contreras wrote:

Show 6 quoted lines

>                                                    It's not my job to
> explain to you that 'git fast-export' doesn't work this way, you have
> a command line to type those commands and see for yourself if they do
> what you think they do with a vanilla version of git. That's exactly
> what I did, to make sure I'm not using assumptions as basis  for
> arguing, it took me a few minutes.

Well no, when I run "git blame" 10 years down the line and do not understand what your code is doing, it is not at all reasonable to expect me to checkout the parent commit, get it to compile with a modern toolchain, and type those commands for myself.

Instead, the commit message should be self-contained and explain what the patch does.

That has multiple parts:

 - first, what the current behavior is

 - second, what the intent behind the current behavior is.  This is
   crucial information because presumably we want the change not to
   break that.

 - third, what change the patch makes

 - fourth, what the consequences of that are, in terms of new use
   cases that become possible and old use cases that become less
   convenient

 - fifth, optionally, how the need for this change was discovered
   (real-life usage, code inspection, or something else)

 - sixth, optionally, implementation considerations and alternate
   approaches that were discarded

If you run "git log", you'll see many good and bad examples to think over and compare to this goal. It's hard work to describe one's work well in terms that other people can understand, but I think it can be satisfying, and in any event, it's just as necessary as including comments near confusing code.

Sincerely, Jonathan