Inside Bitcoin
Opening the selected file…
Inside Bitcoin
Opening the selected file…
The code behind the network, with room to understand it.
Release published 2026-10-28 · Snapshot fetched 2026-11-01. Latest stable release at fetch time; development branches and Git history are excluded. Only the selected code window and visible folders load here.
252When adding a new feature, thought must be given to the long term technical debt253and maintenance that feature may require after inclusion. Before proposing a new254feature that will require maintenance, please consider if you are willing to255maintain it (including bug fixing). If features get orphaned with no maintainer256in the future, they may be removed by the Repository Maintainer.259### Refactoring261Refactoring is a necessary part of any software project's evolution. The262following guidelines cover refactoring pull requests for the project.264There are three categories of refactoring: code-only moves, code style fixes, and265code refactoring. In general, refactoring pull requests should not mix these266three kinds of activities in order to make refactoring pull requests easy to267review and uncontroversial. In all cases, refactoring PRs must not change the268behaviour of code within the pull request (bugs must be preserved as is).270Project maintainers aim for a quick turnaround on refactoring pull requests, so271where possible keep them short, uncomplex and easy to verify.273Pull requests that refactor the code should not be made by new contributors. It274requires a certain level of experience to know where the code belongs to and to275understand the full ramification (including rebase effort of open pull requests).277Trivial pull requests or pull requests that refactor the code with no clear278benefits may be immediately closed by the maintainers to reduce unnecessary279workload on reviewing.282"Decision Making" Process283-------------------------285The following applies to code changes to the Bitcoin Core project (and related286projects such as libsecp256k1), and is not to be confused with overall Bitcoin287Network Protocol consensus changes.289Whether a pull request is merged into Bitcoin Core rests with the project merge290maintainers.292Maintainers will take into consideration if a patch is in line with the general293principles of the project; meets the minimum standards for inclusion; and will294judge the general consensus of contributors.296In general, all pull requests must:298- Have a clear use case, fix a demonstrable bug or serve the greater good of299the project (for example refactoring for modularisation);300- Be well peer-reviewed;301- Have unit tests, functional tests, and fuzz tests, where appropriate;302- Follow code style guidelines ([C++](doc/developer-notes.md), [functional tests](test/functional/README.md));303- Not break the existing test suite;304- Where bugs are fixed, where possible, there should be unit tests305demonstrating the bug and also proving the fix. This helps prevent regression.306- Change relevant comments and documentation when behaviour of code changes.308Patches that change Bitcoin consensus rules are considerably more involved than309normal because they affect the entire ecosystem and so must be preceded by310extensive mailing list discussions and have a numbered BIP. While each case will311be different, one should be prepared to expend more time and effort than for312other kinds of patches because of increased peer review and consensus building313requirements.316### Peer Review318Anyone may participate in peer review which is expressed by comments in the pull319request. Typically reviewers will review the code for obvious errors, as well as320test out the patch set and opine on the technical merits of the patch. Project321maintainers take into account the peer review when determining if there is322consensus to merge a pull request (remember that discussions may have been323spread out over GitHub, mailing list and IRC discussions).325Code review is a burdensome but important part of the development process, and326as such, certain types of pull requests are rejected. In general, if the327**improvements** do not warrant the **review effort** required, the PR has a328high chance of being rejected. It is up to the PR author to convince the329reviewers that the changes warrant the review effort, and if reviewers are330"Concept NACK'ing" the PR, the author may need to present arguments and/or do331research backing their suggested changes.333Moreover, if there is reasonable doubt that the pull request author does not334fully understand the changes they are submitting themselves, or if it becomes335clear that they have not tested the changes on a basic level themselves, the336pull request may be closed immediately.338#### Conceptual Review340A review can be a conceptual review, where the reviewer leaves a comment341* `Concept (N)ACK`, meaning "I do (not) agree with the general goal of this pull342request",343* `Approach (N)ACK`, meaning `Concept ACK`, but "I do (not) agree with the344approach of this change".346A `NACK` needs to include a rationale why the change is not worthwhile.347NACKs without accompanying reasoning may be disregarded.349#### Code Review351After conceptual agreement on the change, code review can be provided. A review352begins with `ACK BRANCH_COMMIT`, where `BRANCH_COMMIT` is the top of the PR353branch, followed by a description of how the reviewer did the review. The354following language is used within pull request comments:356- "I have tested the code", involving change-specific manual testing in357addition to running the unit, functional, or fuzz tests, and in case it is358not obvious how the manual testing was done, it should be described;359- "I have not tested the code, but I have reviewed it and it looks360OK, I agree it can be merged";361- A "nit" refers to a trivial, often non-blocking issue.363Project maintainers reserve the right to weigh the opinions of peer reviewers364using common sense judgement and may also weigh based on merit. Reviewers that365have demonstrated a deeper commitment and understanding of the project over time366or who have clear domain expertise may naturally have more weight, as one would367expect in all walks of life.369Where a patch set affects consensus-critical code, the bar will be much370higher in terms of discussion and peer review requirements, keeping in mind that371mistakes could be very costly to the wider community. This includes refactoring372of consensus-critical code.374Where a patch set proposes to change the Bitcoin consensus, it must have been375discussed extensively on the mailing list and IRC, be accompanied by a widely376discussed BIP and have a generally widely perceived technical consensus of being377a worthwhile change based on the judgement of the maintainers.379### Finding Reviewers381As most reviewers are themselves developers with their own projects, the review382process can be quite lengthy, and some amount of patience is required. If you find383that you've been waiting for a pull request to be given attention for several384months, there may be a number of reasons for this, some of which you can do something385about:387- It may be because of a feature freeze due to an upcoming release. During this time,388only bug fixes are taken into consideration. If your pull request is a new feature,389it will not be prioritized until after the release. Wait for the release.390- It may be because the changes you are suggesting do not appeal to people. Rather than391nits and critique, which require effort and means they care enough to spend time on your392contribution, thundering silence is a good sign of widespread (mild) dislike of a given change393(because people don't assume *others* won't actually like the proposal). Don't take394that personally, though! Instead, take another critical look at what you are suggesting395and see if it: changes too much, is too broad, doesn't adhere to the396[developer notes](doc/developer-notes.md), is dangerous or insecure, is messily written, etc.397Identify and address any of the issues you find. Then ask e.g. on IRC if someone could give398their opinion on the concept itself.399- It may be because your code is too complex for all but a few people, and those people400may not have realized your pull request even exists. A great way to find people who401are qualified and care about the code you are touching is the402[Git Blame feature](https://docs.github.com/en/repositories/working-with-files/using-files/viewing-and-understanding-files). Simply403look up who last modified the code you are changing and see if you can find404them and give them a nudge. Don't be incessant about the nudging, though.405- Finally, if all else fails, ask on IRC or elsewhere for someone to give your pull request406a look. If you think you've been waiting for an unreasonably long time (say,407more than a month) for no particular reason (a few lines changed, etc.),408this is totally fine. Try to return the favor when someone else is asking409for feedback on their code, and the universe balances out.410- Remember that the best thing you can do while waiting is give review to others!413Backporting414-----------416Security and bug fixes can be backported from `master` to release417branches.418Maintainers will do backports in batches and419use the proper `Needs backport (...)` labels420when needed (the original author does not need to worry about it).422A backport should contain the following metadata in the commit body:424```425Github-Pull: #<PR number>426Rebased-From: <commit hash of the original commit>427```429Have a look at [an example backport PR](430https://github.com/bitcoin/bitcoin/pull/16189).432Also see the [backport.py script](433https://github.com/bitcoin-core/bitcoin-maintainer-tools#backport).435Copyright436---------438By contributing to this repository, you agree to license your work under the439MIT license unless specified otherwise in `contrib/debian/copyright` or at440the top of the file itself. Any work contributed where you are not the original441author must contain its license header with the original author(s) and source.
Independent explanations by MyBitcoinExplorer. Not affiliated with or endorsed by Bitcoin Core. Guides are educational and do not replace the source or its tests.
Bitcoin Core source © its contributors, distributed under the MIT license. Original notices and bundled third-party licenses are retained in the source tree.