Suggestion of minor change to patch submission policy re: long descriptions in commit headers
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
Signature · 3 lines
Joshua Lock
Yocto Project "Johannes factotum"
Intel Open Source Technology CentreQuoted 23 lines · 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.
Quoted 4 lines
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
or
Summary
Long description
[BUG #XXXX or URL]
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
Quoted 6 lines
Regards,
Joshua1.
http://openembedded.org/index.php?title=Commit_Patch_Message_Guidelines#New_Development
Quoted 47 lines · Mark Hatle
Quoted 23 lines · 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.
Quoted 4 lines
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]
Quoted 8 lines
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!
Quoted 19 lines
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
Quoted 6 lines
Regards,
Joshua1.
http://openembedded.org/index.php?title=Commit_Patch_Message_Guidelines#New_Development_______________________________________________
Openembedded-core mailing list
[email protected]
http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/openembedded-core
Quoted 11 lines · Joshua Lock
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.
Quoted 10 lines · Phil Blundell
Quoted 9 lines · Joshua Lock
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.
Quoted 8 lines
Quoted 2 lines
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