Proposal for a more unified commit message format
Locked
123
123
Proposal for a more unified commit message format
 
|
Fellow committers,
as you might know, I'm preparing the monthly development details (mostly related to Jiras) for our blog at https://blogs.apache.org/ofbiz/. This is currently a lot of manual work (expecially when we have Community Days!) mostly because the commit messages I use as the source are not unified and written in different formats (Jira reference at the beginning, among the text or end, different line separators, unnecessary or doubled informations like mentioning Jira while also giving the Jira issue etc.). Each developer has his/her own style :-) I'd like to propose a more unified format (or template) for the commit messages which we can put in the Best Practices part of our Wiki. My proposal for a unified format would be: === [Applied patch for|Implemented|Improved|Fix for|Documentation]: [Jira title|Free text] [(OFBIZ-xxxx)] [Details:] [More detailed explanation of what has been done and what the fix achieves, sideeffects etc.] [Thanks:] [xxxx for ... and yyyy for] === Some rules: * line 1 is mandatory, the following lines are optional * line 1: a ":" follows after the kind of implementation/source of work * line 1: the Jira title must not be quoted (""), the Jira reference should be in parenthesis, no whitespace. * no separators between the lines, just new lines This would help a lot for the preparation of the blog and would also make the reading of the commit logs (command line and IDE) much easier, especially when they are displayed as one-liners. What do you think? Regards, Michael Brohl ecomify GmbH www.ecomify.de |
smime.p7s (5K)
Re: Proposal for a more unified commit message format
|
|
Re: Proposal for a more unified commit message format
|
|
Thanks for your suggestion, Pierre!
I thought about that but choose to put it at the end because it's optional (in case we don't have a Jira related to this commit). Regards, Michael Am 06.09.16 um 10:17 schrieb Pierre Smits: > Hi Michael, > > Would it not be more convenient to have the JIRA issue number first? And > then the rest as per your suggestion? > > Best regards, > > > Pierre Smits > > |
Re: Proposal for a more unified commit message format
|
|
There's another reason: in the blog, it's more convenient to have the
Jira reference and link at the end of the description. As long as we do it manually, we would have to cut/paste every Jira reference to the end. Michael Am 06.09.16 um 10:21 schrieb Michael Brohl: > Thanks for your suggestion, Pierre! > > I thought about that but choose to put it at the end because it's > optional (in case we don't have a Jira related to this commit). > > Regards, > > Michael > > > Am 06.09.16 um 10:17 schrieb Pierre Smits: >> Hi Michael, >> >> Would it not be more convenient to have the JIRA issue number first? And >> then the rest as per your suggestion? >> >> Best regards, >> >> >> Pierre Smits >> >> > > |
Re: Proposal for a more unified commit message format
|
|
Re: Proposal for a more unified commit message format
|
Re: Proposal for a more unified commit message format
|
|
Re: Proposal for a more unified commit message format
|
|
In reply to this post by taher
Taher,
I would not put a general limit on the length of the commit message. There are sometimes valuable informations in longer messages I'd like not to miss. Am 06.09.16 um 11:25 schrieb Taher Alkhateeb: > +1 > > I also suggest to have maximum width of 80 characters. This makes things > nicer and cleaner for svn log > > On Tue, Sep 6, 2016 at 11:31 AM, gil portenseigne < > [hidden email]> wrote: > >> Hi Michael, >> >> I like the idea to have unified commit message format. >> >> +1 >> >> Thanks for the proposal ! >> Gil >> >> >> On 06/09/2016 10:08, Michael Brohl wrote: >> >> Fellow committers, >> >> as you might know, I'm preparing the monthly development details (mostly >> related to Jiras) for our blog at https://blogs.apache.org/ofbiz/. >> >> This is currently a lot of manual work (expecially when we have Community >> Days!) mostly because the commit messages I use as the source are not >> unified and written in different formats (Jira reference at the beginning, >> among the text or end, different line separators, unnecessary or doubled >> informations like mentioning Jira while also giving the Jira issue etc.). >> Each developer has his/her own style :-) >> >> I'd like to propose a more unified format (or template) for the commit >> messages which we can put in the Best Practices part of our Wiki. >> >> My proposal for a unified format would be: >> >> >> === >> >> [Applied patch for|Implemented|Improved|Fix for|Documentation]: [Jira >> title|Free text] [(OFBIZ-xxxx)] >> >> [Details:] [More detailed explanation of what has been done and what the >> fix achieves, sideeffects etc.] >> >> [Thanks:] [xxxx for ... and yyyy for] >> >> === >> >> >> Some rules: >> >> * line 1 is mandatory, the following lines are optional >> >> * line 1: a ":" follows after the kind of implementation/source of work >> >> * line 1: the Jira title must not be quoted (""), the Jira reference >> should be in parenthesis, no whitespace. >> >> * no separators between the lines, just new lines >> >> >> This would help a lot for the preparation of the blog and would also make >> the reading of the commit logs (command line and IDE) much easier, >> especially when they are displayed as one-liners. >> >> >> What do you think? >> >> Regards, >> >> Michael Brohl >> ecomify GmbH >> www.ecomify.de >> >> >> >> >> |
Re: Proposal for a more unified commit message format
|
|
Re: Proposal for a more unified commit message format
|
|
In reply to this post by taher
Yes, that might make it clearer.
I will give some examples of existing log messages and how they would look with the new format. Example 1 (old): === Applied patch from jira issue - OFBIZ-8091 - Clean up commented out code in XML for Common component. Thanks Aman for the contribution. === Example 1 (new): === Applied patch for: Clean up commented out code in XML for Common component ( OFBIZ-8091). Thanks: Aman for the contribution. === Example 2 (old): === (OFBIZ-7969) Applied slightly modified patch from jira issue. ================================= Enable adding a content to an agreement ================================= Thanks Leila Mekika for your contribution. === Example 2 (new): === Applied modified patch for: Enable adding a content to an agreement ( OFBIZ-7969). Thanks: Leila Mekika for your contribution. === Example 3 (old): (no Jira) === Improved error message logged by DelegatorFactoryImpl.getInstance(...) when a delegator can't be created; added a TODO comment to remind that the code should be refactored to throw the exception instead. === Example 3 (new): === Improved: error message logged by DelegatorFactoryImpl.getInstance(...) when a delegator can't be created. Details: added a TODO comment to remind that the code should be refactored to throw the exception instead. === Example 4 (old): === A slightly modified Taher's patch for "Load the OWASP dependency checker Gradle plugin efficiently" I reported at OFBIZ-7930 Using OWASP-DC with Gradle was impossible w/o the corresponding plugin. Unfortunately using the suggested way at https://plugins.gradle.org/plugin/org.owasp.dependencycheck loads a lot of dependencies which are only needed by OWASP-DC. So Taher wrote a specific solution to avoid downloading useless libs to a normal use of OFBiz, there it is. jleroux: I have simply formatted the "if(" to "if (" === Example 4 (new): === Applied modified patch: Load the OWASP dependency checker Gradle plugin efficiently (OFBIZ-7930). Details: Using OWASP-DC with Gradle was impossible w/o the corresponding plugin. Unfortunately using the suggested way at https://plugins.gradle.org/plugin/org.owasp.dependencycheck loads a lot of dependencies which are only needed by OWASP-DC. So Taher wrote a specific solution to avoid downloading useless libs to a normal use of OFBiz, there it is. jleroux: I have simply formatted the "if(" to "if (" === Example 2 made me enhance the template: === [Applied patch for|Applied modified patch for|Implemented|Improved|Fix for|Documentation]: [Jira title|Free text] [(OFBIZ-xxxx)] [Details:] [More detailed explanation of what has been done and what the fix achieves, sideeffects etc.] [Thanks:] [xxxx for ... and yyyy for] === Hope that's clearer now? Regards, Michael Am 06.09.16 um 11:26 schrieb Taher Alkhateeb: > Can you include some samples Michael, just for clarity? > > On Tue, Sep 6, 2016 at 12:25 PM, Taher Alkhateeb <[hidden email] >> wrote: >> +1 >> >> I also suggest to have maximum width of 80 characters. This makes things >> nicer and cleaner for svn log >> >> On Tue, Sep 6, 2016 at 11:31 AM, gil portenseigne < >> [hidden email]> wrote: >> >>> Hi Michael, >>> >>> I like the idea to have unified commit message format. >>> >>> +1 >>> >>> Thanks for the proposal ! >>> Gil >>> >>> >>> On 06/09/2016 10:08, Michael Brohl wrote: >>> >>> Fellow committers, >>> >>> as you might know, I'm preparing the monthly development details (mostly >>> related to Jiras) for our blog at https://blogs.apache.org/ofbiz/. >>> >>> This is currently a lot of manual work (expecially when we have Community >>> Days!) mostly because the commit messages I use as the source are not >>> unified and written in different formats (Jira reference at the beginning, >>> among the text or end, different line separators, unnecessary or doubled >>> informations like mentioning Jira while also giving the Jira issue etc.). >>> Each developer has his/her own style :-) >>> >>> I'd like to propose a more unified format (or template) for the commit >>> messages which we can put in the Best Practices part of our Wiki. >>> >>> My proposal for a unified format would be: >>> >>> >>> === >>> >>> [Applied patch for|Implemented|Improved|Fix for|Documentation]: [Jira >>> title|Free text] [(OFBIZ-xxxx)] >>> >>> [Details:] [More detailed explanation of what has been done and what the >>> fix achieves, sideeffects etc.] >>> >>> [Thanks:] [xxxx for ... and yyyy for] >>> >>> === >>> >>> >>> Some rules: >>> >>> * line 1 is mandatory, the following lines are optional >>> >>> * line 1: a ":" follows after the kind of implementation/source of work >>> >>> * line 1: the Jira title must not be quoted (""), the Jira reference >>> should be in parenthesis, no whitespace. >>> >>> * no separators between the lines, just new lines >>> >>> >>> This would help a lot for the preparation of the blog and would also make >>> the reading of the commit logs (command line and IDE) much easier, >>> especially when they are displayed as one-liners. >>> >>> >>> What do you think? >>> >>> Regards, >>> >>> Michael Brohl >>> ecomify GmbH >>> www.ecomify.de >>> >>> >>> >>> >>> |
Re: Proposal for a more unified commit message format
|
|
In reply to this post by taher
Ah, I see, misunderstood you intention.
I think we can take it as a guideline but at command line and e.g. Eclipse you don't have a character count when committing so that could be a hurdle. Am 06.09.16 um 12:00 schrieb Taher Alkhateeb: > Hi Michael, > > I meant a new line after 80 characters. If you review my commit messages > that I usually how I do it (I hit the return key and keep on typing). Not a > big deal but the output becomes nice on most screens. > > On Tue, Sep 6, 2016 at 12:55 PM, Michael Brohl <[hidden email]> > wrote: > >> Taher, >> >> I would not put a general limit on the length of the commit message. There >> are sometimes valuable informations in longer messages I'd like not to miss. >> >> >> Am 06.09.16 um 11:25 schrieb Taher Alkhateeb: >> >> +1 >>> I also suggest to have maximum width of 80 characters. This makes things >>> nicer and cleaner for svn log >>> >>> On Tue, Sep 6, 2016 at 11:31 AM, gil portenseigne < >>> [hidden email]> wrote: >>> >>> Hi Michael, >>>> I like the idea to have unified commit message format. >>>> >>>> +1 >>>> >>>> Thanks for the proposal ! >>>> Gil >>>> >>>> >>>> On 06/09/2016 10:08, Michael Brohl wrote: >>>> >>>> Fellow committers, >>>> >>>> as you might know, I'm preparing the monthly development details (mostly >>>> related to Jiras) for our blog at https://blogs.apache.org/ofbiz/. >>>> >>>> This is currently a lot of manual work (expecially when we have Community >>>> Days!) mostly because the commit messages I use as the source are not >>>> unified and written in different formats (Jira reference at the >>>> beginning, >>>> among the text or end, different line separators, unnecessary or doubled >>>> informations like mentioning Jira while also giving the Jira issue >>>> etc.). >>>> Each developer has his/her own style :-) >>>> >>>> I'd like to propose a more unified format (or template) for the commit >>>> messages which we can put in the Best Practices part of our Wiki. >>>> >>>> My proposal for a unified format would be: >>>> >>>> >>>> === >>>> >>>> [Applied patch for|Implemented|Improved|Fix for|Documentation]: [Jira >>>> title|Free text] [(OFBIZ-xxxx)] >>>> >>>> [Details:] [More detailed explanation of what has been done and what the >>>> fix achieves, sideeffects etc.] >>>> >>>> [Thanks:] [xxxx for ... and yyyy for] >>>> >>>> === >>>> >>>> >>>> Some rules: >>>> >>>> * line 1 is mandatory, the following lines are optional >>>> >>>> * line 1: a ":" follows after the kind of implementation/source of work >>>> >>>> * line 1: the Jira title must not be quoted (""), the Jira reference >>>> should be in parenthesis, no whitespace. >>>> >>>> * no separators between the lines, just new lines >>>> >>>> >>>> This would help a lot for the preparation of the blog and would also make >>>> the reading of the commit logs (command line and IDE) much easier, >>>> especially when they are displayed as one-liners. >>>> >>>> >>>> What do you think? >>>> >>>> Regards, >>>> >>>> Michael Brohl >>>> ecomify GmbH >>>> www.ecomify.de >>>> >>>> >>>> >>>> >>>> >>>> >> |
Re: Proposal for a more unified commit message format
Administrator
|
Re: Proposal for a more unified commit message format
|
|
Re: Proposal for a more unified commit message format
|
|
I agree, the full Url in the commit message first line is too long.
Jacques, where/in which tool do you need the Url? Am 06.09.16 um 14:22 schrieb Taher Alkhateeb: > If we put the full URL in the first line then it might become too long. I > would suggest instead to write the full URL if you want to below the first > line (anywhere you like) and type the first line as Michael suggested. > > On Tue, Sep 6, 2016 at 3:17 PM, Jacques Le Roux < > [hidden email]> wrote: > >> I agree with Michael, here and above. >> >> Just a minor favour, not a problem if not possible. >> >> Would it be tolerable to also use https://issues.apache.org/jira >> /browse/OFBIZ-xxxx instead of OFBIZ-xxxx? >> I like to be able to not have to C/P, and rather just click (how many >> times do I during a day?). >> It's not a problem for Atlassian tools, they parse the same. >> >> Jacques >> >> >> >> Le 06/09/2016 à 12:15, Michael Brohl a écrit : >> >>> Ah, I see, misunderstood you intention. >>> >>> I think we can take it as a guideline but at command line and e.g. >>> Eclipse you don't have a character count when committing so that could be a >>> hurdle. >>> >>> >>> Am 06.09.16 um 12:00 schrieb Taher Alkhateeb: >>> >>>> Hi Michael, >>>> >>>> I meant a new line after 80 characters. If you review my commit messages >>>> that I usually how I do it (I hit the return key and keep on typing). >>>> Not a >>>> big deal but the output becomes nice on most screens. >>>> >>>> On Tue, Sep 6, 2016 at 12:55 PM, Michael Brohl <[hidden email] >>>> wrote: >>>> >>>> Taher, >>>>> I would not put a general limit on the length of the commit message. >>>>> There >>>>> are sometimes valuable informations in longer messages I'd like not to >>>>> miss. >>>>> >>>>> >>>>> Am 06.09.16 um 11:25 schrieb Taher Alkhateeb: >>>>> >>>>> +1 >>>>> >>>>>> I also suggest to have maximum width of 80 characters. This makes >>>>>> things >>>>>> nicer and cleaner for svn log >>>>>> >>>>>> On Tue, Sep 6, 2016 at 11:31 AM, gil portenseigne < >>>>>> [hidden email]> wrote: >>>>>> >>>>>> Hi Michael, >>>>>> >>>>>>> I like the idea to have unified commit message format. >>>>>>> >>>>>>> +1 >>>>>>> >>>>>>> Thanks for the proposal ! >>>>>>> Gil >>>>>>> >>>>>>> >>>>>>> On 06/09/2016 10:08, Michael Brohl wrote: >>>>>>> >>>>>>> Fellow committers, >>>>>>> >>>>>>> as you might know, I'm preparing the monthly development details >>>>>>> (mostly >>>>>>> related to Jiras) for our blog at https://blogs.apache.org/ofbiz/. >>>>>>> >>>>>>> This is currently a lot of manual work (expecially when we have >>>>>>> Community >>>>>>> Days!) mostly because the commit messages I use as the source are not >>>>>>> unified and written in different formats (Jira reference at the >>>>>>> beginning, >>>>>>> among the text or end, different line separators, unnecessary or >>>>>>> doubled >>>>>>> informations like mentioning Jira while also giving the Jira issue >>>>>>> etc.). >>>>>>> Each developer has his/her own style :-) >>>>>>> >>>>>>> I'd like to propose a more unified format (or template) for the commit >>>>>>> messages which we can put in the Best Practices part of our Wiki. >>>>>>> >>>>>>> My proposal for a unified format would be: >>>>>>> >>>>>>> >>>>>>> === >>>>>>> >>>>>>> [Applied patch for|Implemented|Improved|Fix for|Documentation]: [Jira >>>>>>> title|Free text] [(OFBIZ-xxxx)] >>>>>>> >>>>>>> [Details:] [More detailed explanation of what has been done and what >>>>>>> the >>>>>>> fix achieves, sideeffects etc.] >>>>>>> >>>>>>> [Thanks:] [xxxx for ... and yyyy for] >>>>>>> >>>>>>> === >>>>>>> >>>>>>> >>>>>>> Some rules: >>>>>>> >>>>>>> * line 1 is mandatory, the following lines are optional >>>>>>> >>>>>>> * line 1: a ":" follows after the kind of implementation/source of >>>>>>> work >>>>>>> >>>>>>> * line 1: the Jira title must not be quoted (""), the Jira reference >>>>>>> should be in parenthesis, no whitespace. >>>>>>> >>>>>>> * no separators between the lines, just new lines >>>>>>> >>>>>>> >>>>>>> This would help a lot for the preparation of the blog and would also >>>>>>> make >>>>>>> the reading of the commit logs (command line and IDE) much easier, >>>>>>> especially when they are displayed as one-liners. >>>>>>> >>>>>>> >>>>>>> What do you think? >>>>>>> >>>>>>> Regards, >>>>>>> >>>>>>> Michael Brohl >>>>>>> ecomify GmbH >>>>>>> www.ecomify.de >>>>>>> >>>>>>> >>>>>>> >>>>>>> >>>>>>> >>>>>>> >>>>>>> >>> |
Re: Proposal for a more unified commit message format
|
Administrator
|
Re: Proposal for a more unified commit message format
|
|
Hi Jacques,
You can just mark the Jira number in the message, right-click on it and do a Bing search :-) Ok, its not one click though... Am 06.09.16 um 15:36 schrieb Jacques Le Roux: > Le 06/09/2016 à 14:39, Michael Brohl a écrit : >> I agree, the full Url in the commit message first line is too long. >> >> Jacques, where/in which tool do you need the Url? > > Thunderbird mostly to quickly get to the Jira in Firefox w/o C/P the > issue number and add it in an URL in place of an existing issue open, > this to review, follow, etc. > > Taher's idea is OK to me, but anyway I think we don't want to enforce > that as a policy, and if I'm the only "lazy" person, better to forget > it :D. > > Jacques > |
Re: Proposal for a more unified commit message format
|
Administrator
|
Re: Proposal for a more unified commit message format
|
Administrator
|
Re: Proposal for a more unified commit message format
|
|
Re: Proposal for a more unified commit message format
|
|
| Free forum by Nabble | Edit this page |