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

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

[Joshua Lock]

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?

Regards,
Joshua

1.
http://openembedded.org/index.php?title=Commit_Patch_Message_Guidelines#New_Development

-- 
Joshua Lock
        Yocto Project "Johannes factotum"
        Intel Open Source Technology Centre

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

[Mark Hatle]

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
> 

Re: [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@lists.openembedded.org
> http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/openembedded-core

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

[Phil Blundell]

On Tue, 2011-09-13 at 17:46 -0700, Joshua Lock wrote:
> 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.

Agreed, I think this would be something of an improvement (and indeed,
from a look at the git log it appears that some submitters are already
doing this).  Although it isn't a very big deal, I do find it slightly
irritating to have the first line of the long checkin message be
something that is essentially noise.

Possibly even better would be to think up a way to encode the defect
information, in some machine-readable form, as part of the
pseudo-header.  That would make it straightforward for folks who care
particularly about the defect information for (say) yocto to filter it
into some more prominent location.

p.

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

[Richard Purdie]

On Wed, 2011-09-14 at 10:30 +0100, Phil Blundell wrote:
> On Tue, 2011-09-13 at 17:46 -0700, Joshua Lock wrote:
> > 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.
> 
> Agreed, I think this would be something of an improvement (and indeed,
> from a look at the git log it appears that some submitters are already
> doing this).  Although it isn't a very big deal, I do find it slightly
> irritating to have the first line of the long checkin message be
> something that is essentially noise.

In case it wasn't clear, I'm also in favour of moving this to the bottom
of long description rather than the top. 

I think including this information is fine since it does give people
some idea where to look for more information although equally the commit
messages should give suitable information in their own right and this
isn't a replacement for that.

Cheers,

Richard