Re: [PATCH 4/6] gnu: linux-libre-beagle-bone-black: Remove kernel variant.

[Mark H Weaver]

John Darrington <address@hidden> writes:

> On Mon, Sep 26, 2016 at 04:24:10PM +0200, Vincent Legoll wrote:
>      Hello,
>      
>      @David: the following question is nothing against you, I just
>      took the opportunity to ask, sorry for the thread hijacking.
>      
>      On Mon, Sep 26, 2016 at 3:23 PM, John Darrington wrote:
>      > Why are we removing this?
>      
>      Is it just me finding this changelog format usefulness to be
>      very low ?
>      
>
> I entirely agree.   
>
> Our current convention for commit messages is aesthetically pleasing,
> but useless.   It is redundant to put in the message WHAT has changed.
> That can be easily determined by running "git show".   What is much
> more usefull is the reason WHY we changed it.
>
>
> Recently, on another project,  I came across a line of code which I
> was pretty sure was pointless.  I was about to delete it - but I 
> decided to check first.  So I ran "git blame" to find out which 
> commit had added it.  Then I ran git show to get the full details
> of that commit.   Fortunately, the person who had committed it 5 years
> ago had mentioned exactly why it was needed.

Our conventions for commit logs, which follow the GNU Coding Standards
for Change Logs (see section 6.8 of the GNU Coding Standards), is that
explanations belong in the comments of the code itself, not in the
commit log.  If that had been done in the example you give above, you
would have known why the line was needed in a small fraction of the time
that it must have taken you to perform all the steps above.

However, I agree that commits that _remove_ code should include the
rationale in the commit log, if the reason is not obvious and if there's
no sensible place to put the explanation in the code.

What do you think?

      Mark