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

[Saul Wold]

On Tue, 2011-09-13 at 19:58 -0500, Mark Hatle wrote:
> 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.
> 
So, I agree with Mark here, while the reference may not be immediate to
people non familiar with the project directly, it is very helpful to a
maintainer that needs so see this information.  As a maintainer if I
have to constantly read through the long description only to find that I
understand it via a quick reference to a bug number I already know means
additional work. 

If one is not familiar with the bug numbers it's no great pain to skip
this information and read the full description.

I think the general benefit of having the bug number up front is helpful
vs having to scroll for it later in the text. 

Sau!



> 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
> > 
> 
> 
> _______________________________________________
> Openembedded-core mailing list
> Openembedded-core at lists.openembedded.org
> http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/openembedded-core