Hi, can I humbly suggest that we should take a couple of secs to make the commit messages for submitted patches a bit more useful. When looking at the history of the code its useful if the summary gives a brief indication of what has been changed or added by the commit. Good summaries can save a lot of frustrated time wasting when trying to track down where a change has been introduced. Although we flag up the bugzilla bug in the summary, just echoing the bug summary is nearly always counter-productive. The commit should indicate the change introduced not the bug that prompted it. Once the patch is applied the original bug is "background reading" not the main event. It is also misleading if the commit summary says "X is broken" then when that is extracted into the release notes or the gitlog it looks like the commit introduces the breakage of x not vice-versa. It is surely better to have the commit say something along the lines of "Fix broken behaviour in X", which makes it sound a bit more like the desirable feature it no doubt is. A long standing succinct post on commit messages is http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html Colin (Author of some of the world's worst commit messages) -- Colin Campbell Chief Software Engineer, PTFS Europe Limited Content Management and Library Solutions +44 (0) 800 756 6803 (phone) +44 (0) 7759 633626 (mobile) colin.campbell@ptfs-europe.com skype: colin_campbell2 http://www.ptfs-europe.com
I plead guilty :) I already try to follow these instructions but I tend to forget! Do you have some recent examples? Cheers, Jonathan 2015-09-23 9:29 GMT+01:00 Colin Campbell <colin.campbell@ptfs-europe.com>:
Hi, can I humbly suggest that we should take a couple of secs to make the commit messages for submitted patches a bit more useful. When looking at the history of the code its useful if the summary gives a brief indication of what has been changed or added by the commit. Good summaries can save a lot of frustrated time wasting when trying to track down where a change has been introduced. Although we flag up the bugzilla bug in the summary, just echoing the bug summary is nearly always counter-productive. The commit should indicate the change introduced not the bug that prompted it. Once the patch is applied the original bug is "background reading" not the main event. It is also misleading if the commit summary says "X is broken" then when that is extracted into the release notes or the gitlog it looks like the commit introduces the breakage of x not vice-versa. It is surely better to have the commit say something along the lines of "Fix broken behaviour in X", which makes it sound a bit more like the desirable feature it no doubt is.
A long standing succinct post on commit messages is
http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
Colin (Author of some of the world's worst commit messages)
-- Colin Campbell Chief Software Engineer, PTFS Europe Limited Content Management and Library Solutions +44 (0) 800 756 6803 (phone) +44 (0) 7759 633626 (mobile) colin.campbell@ptfs-europe.com skype: colin_campbell2
http://www.ptfs-europe.com _______________________________________________ Koha-devel mailing list Koha-devel@lists.koha-community.org http://lists.koha-community.org/cgi-bin/mailman/listinfo/koha-devel website : http://www.koha-community.org/ git : http://git.koha-community.org/ bugs : http://bugs.koha-community.org/
Mea Culpa. Mea maxima culpa. Thanks for the link, Colin. There are a couple of related issues that I had noticed along the way: 1) Convention (and possibly some koha programming standard) says that the bug number be included in the summary line of the commit message. Somewhere along the line, I assumed that this was an automated thing, so I left them off to avoid duplication :-/ (I'm in the process of fixing those). If we did want to automate this, where would we put it in the process? 2) Knowing which branches a patch has been pushed to is a pain-point for those of us supporting Koha [I know that this is a bit off topic, because this is *not* information that would be stored in the commit message, but bear with me...]. Typically, QA will announce that a patch has been pushed to master, and then the release maintainers for the supported releases will apply the patch to the point releases of the supported Koha version, if applicable. This can cause issues for support because we don't necessarily know what version master was at when the bug was pushed. You can get some sense of this from the date the bug was pushed, and look up release dates, but that's not a straightforward process by any means. I'm not a QA guy, but I assume that we have some release management tool... could we automate the process so that it posted the Koha version number to bugzilla when a bug is pushed to master? Thanks, --Barton On Wed, Sep 23, 2015 at 5:47 AM, Jonathan Druart < jonathan.druart@bugs.koha-community.org> wrote:
I plead guilty :) I already try to follow these instructions but I tend to forget!
Do you have some recent examples?
Cheers, Jonathan
2015-09-23 9:29 GMT+01:00 Colin Campbell <colin.campbell@ptfs-europe.com>:
Hi, can I humbly suggest that we should take a couple of secs to make the commit messages for submitted patches a bit more useful. When looking at the history of the code its useful if the summary gives a brief indication of what has been changed or added by the commit. Good summaries can save a lot of frustrated time wasting when trying to track down where a change has been introduced. Although we flag up the bugzilla bug in the summary, just echoing the bug summary is nearly always counter-productive. The commit should indicate the change introduced not the bug that prompted it. Once the patch is applied the original bug is "background reading" not the main event. It is also misleading if the commit summary says "X is broken" then when that is extracted into the release notes or the gitlog it looks like the commit introduces the breakage of x not vice-versa. It is surely better to have the commit say something along the lines of "Fix broken behaviour in X", which makes it sound a bit more like the desirable feature it no doubt is.
A long standing succinct post on commit messages is
http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
Colin (Author of some of the world's worst commit messages)
-- Colin Campbell Chief Software Engineer, PTFS Europe Limited Content Management and Library Solutions +44 (0) 800 756 6803 (phone) +44 (0) 7759 633626 (mobile) colin.campbell@ptfs-europe.com skype: colin_campbell2
http://www.ptfs-europe.com _______________________________________________ Koha-devel mailing list Koha-devel@lists.koha-community.org http://lists.koha-community.org/cgi-bin/mailman/listinfo/koha-devel website : http://www.koha-community.org/ git : http://git.koha-community.org/ bugs : http://bugs.koha-community.org/
Koha-devel mailing list Koha-devel@lists.koha-community.org http://lists.koha-community.org/cgi-bin/mailman/listinfo/koha-devel website : http://www.koha-community.org/ git : http://git.koha-community.org/ bugs : http://bugs.koha-community.org/
Hi, On Wed, Sep 23, 2015 at 8:42 AM, Barton Chittenden <barton@bywatersolutions.com> wrote:
1) Convention (and possibly some koha programming standard) says that the bug number be included in the summary line of the commit message. Somewhere along the line, I assumed that this was an automated thing, so I left them off to avoid duplication :-/ (I'm in the process of fixing those). If we did want to automate this, where would we put it in the process?
I'm not sure that there's automation for putting the bug number in the subject line of the commit, but there's certainly automation (e.g., the script that builds release notes) that depends on the bug number being there -- (and consequently, the release notes can answer your question about knowing in what versions a bugfix was applied, though I grant that additional indexing might be nice). I share Colin's preference for commit messages that describe the change that the commit makes rather than the bug that the commit fixes -- even more so when the commit message makes it clear how its effects are visible to the user, and what, if anything, the user may need to do about it. Regards, Galen -- Galen Charlton Infrastructure and Added Services Manager Equinox Software, Inc. / The Open Source Experts email: gmc@esilibrary.com direct: +1 770-709-5581 cell: +1 404-984-4366 skype: gmcharlt web: http://www.esilibrary.com/ Supporting Koha and Evergreen: http://koha-community.org & http://evergreen-ils.org
Hi, On Wed, Sep 23, 2015 at 9:13 AM, Galen Charlton <gmc@esilibrary.com> wrote:
I'm not sure that there's automation for putting the bug number in the subject line of the commit, but there's certainly automation (e.g., the script that builds release notes) that depends on the bug number being there -- (and consequently, the release notes can answer your question about knowing in what versions a bugfix was applied, though I grant that additional indexing might be nice).
And to that end, here's a little script I put together just now: http://git.koha-community.org/gitweb/?p=contrib/global.git;a=blob;f=index-re... extract_bugs_from_koha_release_notes: grab bug numbers from Koha release notes This script extracts bug numbers referenced by Koha release notes and outputs a two-column list of version numbers and bugs. It should be run from within a clone of the Koha Git repository; usage is: extract_bugs_from_koha_release_notes > bug_index TODO: this script doesn't currently recognize every way that bugs have gotten cited by release notes. Cheers, Galen -- Galen Charlton Infrastructure and Added Services Manager Equinox Software, Inc. / The Open Source Experts email: gmc@esilibrary.com direct: +1 770-709-5581 cell: +1 404-984-4366 skype: gmcharlt web: http://www.esilibrary.com/ Supporting Koha and Evergreen: http://koha-community.org & http://evergreen-ils.org
That's really going to make my life easier. galen++ Thanks, --Barton On Wed, Sep 23, 2015 at 9:54 AM, Galen Charlton <gmc@esilibrary.com> wrote:
Hi,
On Wed, Sep 23, 2015 at 9:13 AM, Galen Charlton <gmc@esilibrary.com> wrote:
I'm not sure that there's automation for putting the bug number in the subject line of the commit, but there's certainly automation (e.g., the script that builds release notes) that depends on the bug number being there -- (and consequently, the release notes can answer your question about knowing in what versions a bugfix was applied, though I grant that additional indexing might be nice).
And to that end, here's a little script I put together just now:
http://git.koha-community.org/gitweb/?p=contrib/global.git;a=blob;f=index-re...
extract_bugs_from_koha_release_notes: grab bug numbers from Koha release notes
This script extracts bug numbers referenced by Koha release notes and outputs a two-column list of version numbers and bugs.
It should be run from within a clone of the Koha Git repository; usage is:
extract_bugs_from_koha_release_notes > bug_index
TODO: this script doesn't currently recognize every way that bugs have gotten cited by release notes.
Cheers,
Galen -- Galen Charlton Infrastructure and Added Services Manager Equinox Software, Inc. / The Open Source Experts email: gmc@esilibrary.com direct: +1 770-709-5581 cell: +1 404-984-4366 skype: gmcharlt web: http://www.esilibrary.com/ Supporting Koha and Evergreen: http://koha-community.org & http://evergreen-ils.org
Nice script, Galen. I agree with Colin's concern, and I have to admit that I've been fixing several bad commit messages only to make things move faster on the bugfixes queue. BTW, i haven't seen more than 3 or 4 bad commit messages lately. Probably some minor QA followups. 2015-09-23 16:22 GMT-03:00 Barton Chittenden <barton@bywatersolutions.com>:
That's really going to make my life easier.
galen++
Thanks,
--Barton
On Wed, Sep 23, 2015 at 9:54 AM, Galen Charlton <gmc@esilibrary.com> wrote:
Hi,
On Wed, Sep 23, 2015 at 9:13 AM, Galen Charlton <gmc@esilibrary.com> wrote:
I'm not sure that there's automation for putting the bug number in the subject line of the commit, but there's certainly automation (e.g., the script that builds release notes) that depends on the bug number being there -- (and consequently, the release notes can answer your question about knowing in what versions a bugfix was applied, though I grant that additional indexing might be nice).
And to that end, here's a little script I put together just now:
http://git.koha-community.org/gitweb/?p=contrib/global.git;a=blob;f=index-re...
extract_bugs_from_koha_release_notes: grab bug numbers from Koha release notes
This script extracts bug numbers referenced by Koha release notes and outputs a two-column list of version numbers and bugs.
It should be run from within a clone of the Koha Git repository; usage is:
extract_bugs_from_koha_release_notes > bug_index
TODO: this script doesn't currently recognize every way that bugs have gotten cited by release notes.
Cheers,
Galen -- Galen Charlton Infrastructure and Added Services Manager Equinox Software, Inc. / The Open Source Experts email: gmc@esilibrary.com direct: +1 770-709-5581 cell: +1 404-984-4366 skype: gmcharlt web: http://www.esilibrary.com/ Supporting Koha and Evergreen: http://koha-community.org & http://evergreen-ils.org
_______________________________________________ Koha-devel mailing list Koha-devel@lists.koha-community.org http://lists.koha-community.org/cgi-bin/mailman/listinfo/koha-devel website : http://www.koha-community.org/ git : http://git.koha-community.org/ bugs : http://bugs.koha-community.org/
-- Tomás Cohen Arazi Theke Solutions (http://theke.io) ✆ +54 9351 3513384 GPG: B76C 6E7C 2D80 551A C765 E225 0A27 2EA1 B2F3 C15F
Another post (http://chris.beams.io/posts/git-commit/) resumes itself to 7 rules: 1. Separate subject from body with a blank line 2. Limit the subject line to 50 characters 3. Capitalize the subject line 4. Do not end the subject line with a period 5. Use the imperative mood in the subject line 6. Wrap the body at 72 characters 7. Use the body to explain what and why vs. how Rules 1-6 are common to both posts, but I think the 7th is the most important: the "what" and "how" can be found in the diff, but never the "why". Another advice from this post on how to write the subject line:
A properly formed git commit subject line should always be able to complete the following sentence:
If applied, this commit will <your subject line here>
Le 23/09/2015 10:29, Colin Campbell a écrit :
Hi, can I humbly suggest that we should take a couple of secs to make the commit messages for submitted patches a bit more useful. When looking at the history of the code its useful if the summary gives a brief indication of what has been changed or added by the commit. Good summaries can save a lot of frustrated time wasting when trying to track down where a change has been introduced. Although we flag up the bugzilla bug in the summary, just echoing the bug summary is nearly always counter-productive. The commit should indicate the change introduced not the bug that prompted it. Once the patch is applied the original bug is "background reading" not the main event. It is also misleading if the commit summary says "X is broken" then when that is extracted into the release notes or the gitlog it looks like the commit introduces the breakage of x not vice-versa. It is surely better to have the commit say something along the lines of "Fix broken behaviour in X", which makes it sound a bit more like the desirable feature it no doubt is.
A long standing succinct post on commit messages is
http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
Colin (Author of some of the world's worst commit messages)
-- Julian Maurice <julian.maurice@biblibre.com> BibLibre
participants (6)
-
Barton Chittenden -
Colin Campbell -
Galen Charlton -
Jonathan Druart -
Julian Maurice -
Tomas Cohen Arazi