The Bitcoin Core Merge Process

A major point of confusion, especially among people who have not worked a lot on free open source software development, is how Bitcoin Core makes changes to its code. I adapted a post I had previously made as a response to another article since I believe this topic deserves its own post.

Commit access, the ability to add new commits to the Bitcoin Core codebase, is a maintenance role…making sure the repository doesn’t get vandalized and that only commits that have wide support or are otherwise no-brainers get merged. It is a misconception that only people with commit access are able to make changes to code. Merging the changes is merely the last step of a long process. People with commit access are called maintainers.

If a maintainer were to start merging stuff irresponsibly, other developers would either insist on revoking their commit access or would fork the project to a separate repository and get other developers to join that one instead where commit access can be reassigned however they want.

Anyone can fork the codebase repository and make arbitrary changes to their own repository. They can build a client from their own repository and run that instead if they want. They can also make binary builds for other people to run.

If someone wants to merge a change they’ve made in their own repository into Bitcoin Core, they can submit a pull request. Once submitted, anyone can review the changes and comment on them regardless of whether or not they have commit access to Bitcoin Core itself.

Others can even clone the repository locally and compile and run the program with the changes for themselves on their own machine, or make additional modifications and submit them as proposals. These proposals can also be discussed. These discussions often go on for many days, sometimes even weeks or months (especially for security-critical or consensus changes), with the original author taking suggestions from peers and making changes and corrections.

Only once there are no more reasonable objections will a maintainer merge the code.

Maintainers must pass through the exact same peer review process as everyone else when submitting proposals. They must also fork the codebase repository and make proposed changes to their own copy. They must submit a pull request before merging any nontrivial change and have it reviewed by others. Merging any nontrivial change without review is a violation of the process and could result in the maintainer’s commit access getting revoked.

Consensus changes go well beyond code changes. There are two basic kinds of consensus changes: hard forks and soft forks. Hard forks result in a chain split, where different nodes will end up on separate chains and will see a different ledger, unless all nodes on the network are updated. Soft forks do not result in a chain split as long as they are ultimately supported by sufficient hashpower since that will ensure all nodes ultimately converge on the chain with the most proof-of-work.

Despite one chain having more hashpower than the other at the time of a fork, it can still be overtaken in hashpower later on. Hard forks and soft forks can be further subdivided into different classes depending on their behavior in these situations.

In order to make a consensus change, it is not only necessary to merge the code into the repository — it is also necessary to get other people on the network to run that code. And Bitcoin Core has, as a project, generally been very conservative when it comes to these sorts of changes. These changes require a deep understanding of not only the protocol but of game theory and politics as well, particularly if a change is likely to cause different players to have divergent interests.

Consensus changes that are likely to cause divergent interests are almost always avoided. And ensuring that a consensus change will not cause divergent interests is in general an extremely difficult problem which even seasoned experts sometimes get wrong. Any introduction of an incompatibility is liable to create divergent interests on the network and is not to be taken lightly!