How to make it easy for a maintainer to apply your patch

• If you don’t know git, take a day or two to learn (it’s not that hard, and the gitk and git-gui GUI tools can help a lot)
• Read through the existing commit messages to get a feel for the common style – and try use this style in your own commit messages:
  • A one-line summary as the 1st line of the commit message. You may wish to start it with ‘applicability:’, e.g. ‘bgpd:’, ‘netlink:’, ‘freebsd:’, etc. This is used for release announcements.
  • The body of the commit message, containing a high-level description of the goal of the changes, including the problem being addressed and the reasoning for the commit, on a change by change basis (e.g. per file, even per-function, if that’s appropriate). For a large commit, an introductory overview may be needed.The goal is two-fold: To force the submitter to perform a self-review of the commit (and so catch problems); and to give the reader the required context to review the commit.
  • An honest indication of the confidence you have in the patch, including what, if any testing has been done.
  • If the patch contains work done by others, e.g. because it is a rework of some other patch, indicate this. Though, ideally, the original patch should be a separate commit, attributed correctly with the –author argument to git-commit.
• Read the HACKING document (parts are out of date though)
• Prepare a branch, based on the Quagga.net master, that contains your changes and nothing else (merges from master are ok; if you need to merge it together with other things for your own purposes, then use another branch – they’re cheap).
• If you like to rebase published branches, please name-space such branches with a ‘volatile/’ prefix.
• Order the commits so the that the safest, least-contraversial commits are earlier in the branch than patches that are less likely to be mergeable. This allows maintainers to, perhaps, still be able to pull part of your branch if some patches are deemed problematic.
• If you have a large and/or less-obviously-safe patch, try to split the patch up into smaller ones. E.g. there may be infrastructural improvements that can be factored out and go in first.

It’s extremely rare that contributors do all of the above. Commit messages in particular are often free-form. Sometimes they describe the problem, but not why the change fixes it. Sometimes the change is described, but without reference to the problem. Sometimes the message is akin to a C-to-english transliteration.

It might seem like a pain to force submitters to spend 5 to 10 minutes to go through their patch and construct a structured, detailed, but high-level description of their patch and their intent. However not doing so forces the reviewer to spend even more time to mentally construct the same. If you have many contributors feeding patches to a small number of maintainers, then it just doesn’t scale unless contributors make an effort to make their patches as reviewable and easy-to-integrate as possible.

In short, try to make life easy for your maintainer. There are several small, maybe even apparently trivial, things you can do quite easily which help reduce their load, and help smooth your patches’ path.

Updates: Git strips out []’s, so change section recommending patch subjects encode information in them.