Monthly Archives: April 2013

The commit police: learning for recent reference mistakes

Continuing the previous post about commits and bugs, I’d like to review some mistakes I saw recently. Mistakes do happen, but mentioning them here is meant to teach others and hopefully to reduce similar ones in the future. This post isn’t about shaming the authors/commiters. Also, the points I highlight are what I consider as a mistakes or problems, other people might think differently.

  1. Mentioning two bugs in one commit message, which our system doesn’t support right now. So the second bug doesn’t get the commit notification, and that should be done manually (example: commit 2933935 and fdo#53278).
  2. Referencing gerrit changes as part of the commit message (example: commit 87f185d). Giving references as part of the commit is great and helpful, but I would prefer to see the reference to the actual commit and not to its review process. This is meaningful when you search the log. If the followup change is suggested when the first change is still in review it should be combined, otherwise it already have a commit to reference.
  3. Following up a commit, and not mentioning the bug it references (example: commit 87f185d). In this specific case, the we’re talking about a meta bug for translating comments from German to English (fdo#39468), so no harm done. But this important when you want to cherry pick a fix for a bug to other branches and might forget the follow up commits. It’s also relevant to more technical meta bugs (example: fdo#62096).
  4. Referencing a mailing list which reference a commit and a bug instead of referencing them directly (commit 21fea27, fdo#60534). This bug shows very well why correct referencing is important, a commit was made to fix the bug, a follow up commit was done without proper reference, and than the first commit was reverted. No one involved in trying to fix that specific bug knew about the follow up commit as it wasn’t documented anywhere.
  5. Referencing bugs though full bug URL instead of the right format (example: commit e1f6dac). Also the bug is referenced in the commit in the body of the message instead of the first line (header) which is more visible.
  6. Referencing non existing bugs (example: commit 3a4534b). Which got a manual notification in the bug by the comitter (fdo#33091).
  7. Using shortening services URL as part of commit messages (example: commit 86f8fba). There’s no way to know to what the reference is without using the service, which in this case was leading to a post on one of the projects mailing list. There isn’t any problem giving the direct URL to the list’s archive. It’s interesting whether we should link to our URL and is it “OK” to use other external services who also archive our mailing lists (example: commit e83990a).

To conclude, having references in commit message is really helpful, but please reference the right resource to help people find it easily and to let our automated services parse it.

1 Comment

Filed under LibreOffice

The commit police: reference you bugs properly

Besides my RTL work on Libreoffice, every once in a while I just go over the regular commit log to see what have changed. I don’t necessary understand each line in the commit, but do get the general idea from the commit message. Being more dependent on the commit messages makes me review them more thoroughly (hence the topic of this post).

As many projects, Libreoffice has notifications of commits related to bugs reports when the bug number is properly mentioned in the commit message. This is very useful for other developers and also for QA people. After verification of a bug is fixed, I often use the commits listed on the bug report to cherry pick them to an older branch. Going to search for an unreferenced commit isn’t much fun.

One of the things I notice is different ways people reference bugs – from not referencing them at all to referencing them in various ways like linking to the bugs system, just writing the number (without the fdo# prefix) and other creative ways… This is also true for first time contributors, which might not know the standards or the “rules”. When I see such a case I usually put a manual notification in the bug report, and mail the author of doing so. For new or sporadic contributors this is also an opportunity to welcome and thank them for the commit and even encourage future contributions.

I have been asked why aren’t that info on the wiki, so I went looking and found out the info is in the right place under the “Development/GetInvolved” page. The relevant part is:

When you type a commit message:

  • start the first line with a bug reference like fdo#12345, if you have one for your commit (see details below)
  • use the rest of the first line as a concise summary of your changes
  • the 2nd line remains empty
  • and starting on the 3rd line you can explain how and what changes have been made for what reasons.

Thanks in advance and happy coding (:

1 Comment

Filed under LibreOffice