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.
- 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).
- 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.
- 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).
- 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.
- 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.
- Referencing non existing bugs (example: commit 3a4534b). Which got a manual notification in the bug by the comitter (fdo#33091).
- 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.