Patchsets for Dinner

Oh, I just came up with a really good metaphor for how to create a good looking patchset:

A patch should be one logical change. For example, you should put all whitespace changes in one patch. If you’re changing variable names to avoid CamelCase, you should do only one variable name change per patch. Basically, you’re breaking up patches into the smallest logical unit necessary, in order to make it easy to read and review. A patch that’s over a hundred lines is going to be pretty hard to review.

Think of it this way: you’re preparing a big meal for a friend, and you have many different dishes you want to serve them. You don’t throw all the food into one big pot and serve it to them. Instead, you serve each part of the meal on separate plates, so that they can admire your cooking, and you take the time to explain how you prepared each dish, and why it’s tasty.

A good patchset is like a well-prepared meal. You provide a menu (cover letter or patch zero) that explains what you’re going to serve (what the overall goal of the patchset is), and bite-sized portions (one logical change per patch) beautifully arranged (documented, signed, and up to coding style) in a particular order (numbered patches, with bug fixes and refactoring first).

It takes a while to learn how to cook a full course meal, and even longer to figure out how to present it with a flourish. People new to Linux kernel development should work on sending bite-sized, smaller patches, with one logical change per patch. Once you’ve got that down, you can work on presentation of multiple patches.