[Koha-devel] Write good bug report titles and commit messages

Jonathan Druart jonathan.druart at bugs.koha-community.org
Thu Aug 31 16:10:09 CEST 2017


Hi devs,

I would like to do a little reminder about the bug report titles and commit
messages.

For bugs:
The bug report title must shortly tell what the *bug* is, whereas the
commit messages must tell what the *fix* does. Sometimes they are not
related at all.
For instance:
- bug report titles: "Feature X is not working correctly when Y is
enabled", "Click on button 'Save' does not save the record", "Saving stuff
on screen X does not work", "This script generates error logs", "Mystake is
misspelled in this script", "Behaviour X no longer work as expected" etc.
- commit messages: "Fix Feature X when Y is enabled", "Make sure behaviour
is correct when button is clicked", "Remove warnings from this script",
"Correct spelling of mistake in this script", "Fix regression on behaviour
X" etc.

For enhancements / new feature:
We could have the same title and commit messages in some cases.
- bug report titles: "Add new awesome feature", "Add the ability to do
that", "Code is duplicated in method Koha::Stuff->method"
- commit messages: "Add new awesome feature", "Add the ability to do that",
"Remove code duplication in method Koha::Stuff->method"

Note that "Address comment #42" is a terrible commit message.

Then, I would like to standardize the commit messages a bit.
We have "Bug 12345 - ", "Bug 12345: ", "Bug 12345"
and "[follow-up]", "(follow-up)", "[QA Followup]", etc.

I would suggest:
  "Bug 12345: you commit message"
And reject any commit messages with only "follow-up" (or whatever how it is
written), but accept
  "Bug 12345: (follow-up) same commit message as before"
If you forgot something, even if
  "Bug 12345: (follow-up) This was missing"

And QA follow-ups (added by QA team member):
  "Bug 12345: "(QA follow-up) Add/remove this stuff"

I am going to suggest these change during the next dev meetings.
If accepted I will change the bug report titles and commit messages before
the push during few weeks, then ask authors to do it themselves (patches
from new contributors will not be rejected for that reason).

You should also read or re-read:
https://wiki.koha-community.org/wiki/Bug_Reporting_Guidelines
https://wiki.koha-community.org/wiki/Commit_messages

Cheers,
Jonathan
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.koha-community.org/pipermail/koha-devel/attachments/20170831/327273f8/attachment-0001.html>


More information about the Koha-devel mailing list