Re: [RFC] Suggestion of minor change to patch submission policy re: long descriptions in commit headers

[Mark Hatle <mark.hatle@windriver.com>]

On 9/13/11 7:46 PM, Joshua Lock wrote:
> Our patch submission policy[1] 
> 
> "Optionally, you may include pointers to defects this change corrects.
> Unless the defect format is specified by the component you are
> modifying, it is suggested that you use a full URL to specify the
> reference to the defect information. Generally these pointers will
> precede any long description, but as an optional item it may be after
> the long description."
> 
> I've been guilty of always having the defect id after the description,
> and have never included the defect URL (though my reading suggests this
> is not required for Yocto defects I still believe this will make the
> defect id's more useful for fellow OE-Core developers).
> 
> Whilst I intend to rectify the latter I'd like to propose we change the
> former such that the defect information is at the end of the commit
> message.
> 
> I believe this is more suitable for the project because the defect
> information and its relevance should be summarised in the long
> description, and therefore the defect id and link to the defect tracker
> are supplemental information for interested readers.
> 
> IMHO this supplementary nature should lead us to request submitters
> provide defect information after the long description.
> 
> Thoughts?

We talked about this a bit while doing the original guidelines.  We debated between:

  Summary

  [BUG #XXXX or URL]

  Long description

  Signed-off-by:...

or

  Summary

  Long description

  [BUG #XXXX or URL]

  Signed-off-by:...

The former was chosen simply cause it shows the reader that we have a fixed a
bug (at the external reference) without them having to read or skim the long
description.  I can't say I care either way, other then I agree the former is a
bit quicker to read -if- the goal of reading is to determine which commits are
bug fixes, vs general development.

BTW -- [YOCTO #XXXX] is one of the "well defined" formats that is mentioned in
the guidelines document.  But if I was to point to a bug fix in say the GNU Hurd
bugzilla (is there such a bugzilla?) that should likely contain the full URL, as
people won't be used to seeing it...

--Mark

> Regards,
> Joshua
> 
> 1.
> http://openembedded.org/index.php?title=Commit_Patch_Message_Guidelines#New_Development
>