Re: [Koha-devel] git commit messages

[Julian Maurice]

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 


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 
BibLibre
___
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/

Re: [Koha-devel] git commit messages

[Barton Chittenden]

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.dru...@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 :
> > 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.campb...@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/
>
___
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/

Re: [Koha-devel] git commit messages

[Galen Charlton]

Hi,

On Wed, Sep 23, 2015 at 8:42 AM, Barton Chittenden
 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:  g...@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/

Re: [Koha-devel] git commit messages

[Galen Charlton]

Hi,

On Wed, Sep 23, 2015 at 9:13 AM, Galen Charlton  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-release-notes/extract_bugs_from_koha_release_notes;hb=HEAD

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:  g...@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/

Re: [Koha-devel] git commit messages

[Tomas Cohen Arazi]

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 :

> That's really going to make my life easier.
>
> galen++
>
> Thanks,
>
> --Barton
>
>
> On Wed, Sep 23, 2015 at 9:54 AM, Galen Charlton 
> wrote:
>
>> Hi,
>>
>> On Wed, Sep 23, 2015 at 9:13 AM, Galen Charlton 
>> 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-release-notes/extract_bugs_from_koha_release_notes;hb=HEAD
>>
>> 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:  g...@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
___
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/

Re: [Koha-devel] git commit messages

[Barton Chittenden]

That's really going to make my life easier.

galen++

Thanks,

--Barton


On Wed, Sep 23, 2015 at 9:54 AM, Galen Charlton  wrote:

> Hi,
>
> On Wed, Sep 23, 2015 at 9:13 AM, Galen Charlton 
> 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-release-notes/extract_bugs_from_koha_release_notes;hb=HEAD
>
> 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:  g...@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/

[Koha-devel] git commit messages

[Colin Campbell]

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.campb...@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/

Re: [Koha-devel] git commit messages

[Jonathan Druart]

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 :
> 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.campb...@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/