What do you do if you run into a bear in the forest? Ask him to review a pull request, he’ll pretend not to see you and pass you right by.

Creating Pull Requests

It is important to remember that there are many people subscribed to the repository, and any changes to a pull request will trigger notifications to tens, hundreds, or potentially thousands of people. As such, try to minimize them, or else many people, including maintainers, will unsubscribe, and response time for issues and pull request changes will increase dramatically.

Before even submitting a pull request, make sure to do a thorough self-review. This will allow you to spot minor issues like typos or code you didn't intend to commit in the first place. At this stage, use force-pushes to edit original commits to make sure you like the changes yourself.

Commits

Commits should tell a logical step-by-step story of the changes and should be individually meaningful. Use squashing and rebasing during development, reorder commits if it makes more sense that way; there is great tooling out there for these kinds of modifications.

A reviewer should be able to go through commits one by one and understand what is being changed. With non-trivial changes it is often very hard to review the final diff, so going through commits helps a lot. Commits should be well-structured and there should be a reasonable number of them. Having 70 commits for 100 lines or changes is most likely bad, same with one commit that changes many thousands of lines of code in various places at once (lock files are a frequent and notable exception).

If you are working on a branch and after a few commits notice that API introduced earlier doesn't work well or you need to revert some changes, amend the original commit instead of creating a new one. A reviewer going through individual commits will likely have a comment about something that was already fixed and will simply have to spend more time reviewing changes back and forth.

Different kinds of changes should ideally be in different commits if not pull requests entirely. For instance, if you want to move something and change something, move it in one commit so the reviewer can have a quick look without thinking about it too much, then apply the actual changes in a separate commit. The same should be done with file renaming, if you rename a file and change it significantly in the same commit it will make the reviewer's life very difficult and likely convince Git that one file was deleted and another file added, which breaks tooling for tracking file changes across renames.

It is sometimes the case that some refactoring needs to be done during feature development. If so, try to extract those refactoring commits you have just done into a separate branch, submit it for review, and rebase your working branch on the refactoring branch so that the changes are clearly separated and easier to review.

Please push your commits regularly, but not necessarily every commit since it may occupy CI time unnecessarily and/or distract maintainers.

And finally, write commit messages in the present tense (as opposed to past tense) and explain changes that should be done. For example:

finalize header at archiving depth and prune any forks at that number

Avoid garbage commit names like "fix", "wip", "🤦 x 2", "......", "AHHHHHHHHH" (those are real examples). In most cases, those commits probably shouldn't exist separately and better squashed with some other commit.

For more information on both why a well-formed commit history matters and a guide on how to accomplish it read Write Better Commits, Build Better Projects.

Tested

Make sure to test your own code locally and/or in CI before submitting a pull request. This avoids generating notifications to everyone subscribed to the repository for subsequent fixes to CI. If you need to test fixes for CI issues for a branch that already has PR created for it, create a different test branch and push/force-push commits there until CI is fixed. Make sure to add new test cases if applicable.

Understandable

As explained in the commits section above, the commit history should be clean and readable, ready for the reviewer to go through and make sense of the changes proposed.