Commit messages

From Koha Wiki

Jump to: navigation, search
Home
Koha > Technical > Development

When you submit code to the project (using Git) please write useful commit messages. On this page you will find an example commit message, as well as a detailed analysis of what's in it.

Contents

Good commit messages

    Bug 9070: authority searches in auth_finder error out
    
    When using authority records imported into Koha from elsewhere, you
    can get an error like:
        Can't use string ("HASH(0xbc6c{30)") as a HASH ref while "strict refs" in use at /usr/share/koha/lib/C4/AuthoritiesMarc.pm line 363.
    in authorities/auth_finder.pl. This patch fixes that error.
    
    To test:
    1) You will need records imported from elsewhere.
    2) Use the authority control plugin in a bib record to search for one of
       those headings.
    3) Observe you get a nasty error.
    4) Apply patch.
    5) Repeat step 2.
    6) Observe the error is gone.
    7) Sign off.

    Sponsored-by: The Library

    Signed-off-by: Magnus Enger <magnus@...>
    Works as advertised. No warning about "defined(%hash) is deprecated"
    under perl v5.10.1.

Subject line

    Bug 9070: authority searches in auth_finder error out

The first line of a commit message is the subject. The subject should *always* provide a bug number and a brief description, ideally in 50 characters or fewer.

The bug number must be the very first thing on the line, and be formatted like "Bug 1234."

Bug/feature description

    When using authority records imported into Koha from elsewhere, you
    can get an error like:
        Can't use string ("HASH(0xbc6c{30)") as a HASH ref while "strict refs" in use at /usr/share/koha/lib/C4/AuthoritiesMarc.pm line 363.
    in authorities/auth_finder.pl. This patch fixes that error.

A description of what problem the bug addresses, or what feature it adds. If it's a very simple patch, this might be covered by the subject line, but probably not. Often you can get this by copying the description of the bug out of Bugzilla and into your commit message, or by including relevant parts of your RFC in the commit message. Whenever possible, this should be wrapped at 72 characters, though error messages and file paths/URLs will often have to go longer.

Documentation notes

If there are particular things that the documentation team should know about, a note to that effect should be included in the commit message. For example, a list of system preferences, new permissions, and new cron jobs might be appropriate, depending on the patch.

Test plan

    To test:
    1) You will need records imported from elsewhere.
    2) Use the authority control plugin in a bib record to search for one of
       those headings.
    3) Observe you get a nasty error.
    4) Apply patch.
    5) Repeat step 2.
    6) Observe the error is gone.
    7) Sign off.

A detailed test plan, with a clear heading. It should include enough detail that it could be followed by someone familiar with Koha who does not use whatever section of the code you are editing. A test plan with forty steps may seem daunting, but it really isn't. It's considerate. Ideally, the test plan should cover how to confirm the bug *and* how to confirm that the patch fixed the problem, if the two procedures are not entirely identical (for example, if your patch involves Zebra configuration changes, note which files need to be updated; I favor a tl;dr section which includes information of this sort). Again, this should be wrapped at 72 characters where possible, and use a hanging indent..

Including a "sign off" step is unnecessary, of course.

    Sponsored-by: The Library

If your patch was sponsored by an institution that wants credit in the release notes, add a Sponsored-by: line with the name of the institution as you would like it to appear.

Signoffs/QA Signoffs

    Signed-off-by: Magnus Enger <magnus@...>
    Works as advertised. No warning about "defined(%hash) is deprecated"
    under perl v5.10.1.

When signing off or QAing a patch, you should add your Signed-off-by: line by using `git commit -s` and add a (brief) description of what you tested.

A gentle reminder: if there is information needed for testing a patch, it should be in your commit message, not just in comments on the bug. If -- in the course of looking at a patch for pushing to Master -- I follow the test instructions in a commit message and the patch does not work, or if I can't quickly divine what the patch is about, I will ask for clarification and move on. If I don't understand, I have no reason to think that I will start to understand after spending more time on the issue, and any time I spend not understanding one patch is time during which no other patch is getting reviewed.

Formatting

Ideally we are shooting for a subject which is 50 characters or fewer, and the body of commit messages should be wrapped at 72 characters. A good blog post on this topic can be found at http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

Bad commit messages

The worst kind of commit message is an inaccurate one, followed closely by an empty one.


Developer handbook

Personal tools