Contributing code

This section details some of the processes surrounding code contributions to the Bitcoin Core project along with some common pitfalls and tips to try and avoid them.

Branches

You should not use the built-in GitHub branch creation process, as this interferes with and confuses the Bitcoin Core git process.

Instead, you should use either the native git or the GitHub gh cli (requires git) tools to create your own branches locally, before pushing them to your fork of the repo, and opening a PR against the Bitcoin Core repo from there.

Creating a PR

Jon Atack’s article How To Contribute Pull Requests To Bitcoin Core describes some less-obvious requirements that any PR you make might be subjected to during peer review, for example that it needs an accompanying test, or that an intermediate commit on the branch doesn’t compile. It also describes the uncodified expectation that Contributors should not only be writing code, but perhaps more importantly be providing reviews on other Contributors' PRs. Most developers enjoy writing their own code more than reviewing code from others, but the decentralized review process is arguably the most critical defence Bitcoin development has against malicious actors and therefore important to try and uphold.

Jon’s estimates of "5-15 PR reviews|issues solved" per PR submitted is not a hard requirement, just what Jon himself feels would be best for the project. Don’t be put off submitting a potentially valuable PR just because "you haven’t done enough reviews"!

For some tips on how to maintain an open PR using git, such as how to redo commit history, as well as edit specific commits, check out this guide.

Commit messages

When writing commit messages be sure to have read Chris Beams' "How to Write a Git Commit Message" blog post. As described in CONTRIBUTING.md, PRs should be prefixed with the component or area the PR affects. Common areas are listed in CONTRIBUTING.md section: Creating the pull request. Individual commit messages are also often given similar prefixes in the commit title depending on which area of the codebase the changes primarily affect.

Unless there is a merge conflict (usually detected by DrahtBot), don’t rebase your changes on master branch before pushing. If you avoid rebases on upstream, Github will show a very useful "Compare" button which reviewers can often use to quickly re-ACK the new changes if they are sufficiently small. If you do rebase this button becomes useless, as all the rebased changes from master get included and so a full re-review may be needed. Developer review time is currently our major bottleneck in the project!