Useful Links

News!

Submitting Patches

The guiding principal is typically expressed as "one change per patch; one patch per change". That is, the fundamental property of interest is not size, but the number of logically separate changes which are part of the same patch. The correct number is always exactly one.

Multiple related edits like changing a function's prototype, making the corresponding change to its definition, and updating all of the call sites are really a single change, and should be part of the same patch, and thus the same commit.

The same goes for a group of edits spread across the tree that introduce a new feature or fix a bug. If they're part of one logical change, they should be part of one commit. A good rule to use here is to combine things that are syntactically or semantically interdependent, such that applying only part of the change results in a tree that doesn't build or that no longer works correctly.

The flip side is that unrelated things should generally not be part of the same patch. Don't fix a bug and add a feature in the same patch. Or fix two bugs, or add two features. That goes triple for keeping cosmetic/stylistic changes such as a reindent separate from warning elimination, and both separate from actual functional changes. Similarly, any new code should follow the same formatting conventions as the existing code, for indentation, location of braces, etc.

Putting unrelated changes in the same patch makes that patch harder to review, makes it harder to accept one change but not the other (which may result in the whole thing being rejected), and makes it harder to track down what happened if one of those changes introduced a bug. "git bisect" is a powerful tool for tracking down when a problem was introduced, but can't split the difference between two changes that were part of the same commit.

It is often be possible to take a large set of changes to add a complex new feature, and break it down into smaller parts, each building on the last. Such things are often easier to review and test, which is always a good thing.

The patch guide on github has good instructions for submitting changes. If the patch is small, it can be submitted to the list. See the file doc/DIFFS.rst for additional instructions.