1Contributing to Bitcoin Core
2============================
3
4The Bitcoin Core project operates an open contributor model where anyone is
5welcome to contribute towards development in the form of peer review, testing
6and patches. This document explains the practical process and guidelines for
7contributing.
8
9First, in terms of structure, there is no particular concept of "Bitcoin Core
10developers" in the sense of privileged people. Open source often naturally
11revolves around a meritocracy where contributors earn trust from the developer
12community over time. Nevertheless, some hierarchy is necessary for practical
13purposes. As such, there are repository maintainers who are responsible for
14merging pull requests, the [release cycle](/doc/release-process.md), and
15moderation.
16
17Getting Started
18---------------
19
20New contributors are very welcome and needed.
21
22If you use AI tools while contributing, please read and follow the [AI
23policy](/doc/AI_POLICY.md). Contributors are responsible for understanding and
24explaining their own work in their own words.
25
26In-depth reviewing and testing are the bottleneck of the project, and are the
27most effective way anyone can start to contribute. It will teach you much more
28about the code and process than opening pull requests, and may help you uncover
29related issues and follow-ups to contribute code for. Please refer to the [peer
30review](#peer-review) section below.
31
32Before you start contributing, familiarize yourself with the Bitcoin Core build
33system and tests. Refer to the documentation in the repository on how to build
34Bitcoin Core and how to run the unit tests, functional tests, and fuzz tests.
35
36You may also participate in the [Bitcoin Core PR Review Club](https://bitcoincore.reviews/).
37
38Communication Channels
39----------------------
40
41Most communication about Bitcoin Core development happens on IRC, in the
42`#bitcoin-core-dev` channel on Libera Chat. The easiest way to participate on IRC is
43with the web client, [web.libera.chat](https://web.libera.chat/#bitcoin-core-dev). Chat
44history logs can be found
45on [https://www.erisian.com.au/bitcoin-core-dev/](https://www.erisian.com.au/bitcoin-core-dev/)
46and [https://gnusha.org/bitcoin-core-dev/](https://gnusha.org/bitcoin-core-dev/).
47
48Discussion about codebase improvements happens in GitHub issues and pull
49requests.
50
51The developer
52[mailing list](https://groups.google.com/g/bitcoindev)
53should be used to discuss complicated or controversial consensus or P2P protocol changes before working on
54a patch set.
55Archives can be found on [https://gnusha.org/pi/bitcoindev/](https://gnusha.org/pi/bitcoindev/).
56
57
58Contributor Workflow
59--------------------
60
61The codebase is maintained using the "contributor workflow" where everyone
62without exception contributes patch proposals using "pull requests" (PRs). This
63facilitates social contribution, easy testing and peer review.
64
65Pull request authors must fully and confidently understand their own changes
66and must have tested them. Contributors should mention which tests cover their
67changes, or include the manual steps they used to confirm the change.
68Contributors are expected to be prepared to clearly motivate and explain their
69changes. If there is doubt, the pull request may be closed.
70Please refer to the [peer review](#peer-review) section below for more details.
71
72To contribute a patch, the workflow is as follows:
73
74  1. Fork repository ([only for the first time](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo))
75  1. Create topic branch
76  1. Commit patches
77
78For GUI-related issues or pull requests, the https://github.com/bitcoin-core/gui repository should be used.
79For all other issues and pull requests, the https://github.com/bitcoin/bitcoin node repository should be used.
80
81The master branch for all monotree repositories is identical.
82
83As a rule of thumb, everything that only modifies `src/qt` is a GUI-only pull
84request. However:
85
86* For global refactoring or other transversal changes the node repository
87  should be used.
88* For GUI-related build system changes, the node repository should be used
89  because the change needs review by the build systems reviewers.
90* Changes in `src/interfaces` need to go to the node repository because they
91  might affect other components like the wallet.
92
93For large GUI changes that include build system and interface changes, it is
94recommended to first open a pull request against the GUI repository. When there
95is agreement to proceed with the changes, a pull request with the build system
96and interfaces changes can be submitted to the node repository.
97
98The project coding conventions in the [developer notes](doc/developer-notes.md)
99must be followed.
100
101### Committing Patches
102
103In general, [commits should be atomic](https://en.wikipedia.org/wiki/Atomic_commit#Atomic_commit_convention)
104and diffs should be easy to read. For this reason, do not mix any formatting
105fixes or code moves with actual code changes.
106
107Make sure each individual commit is hygienic: that it builds successfully on its
108own without warnings, errors, regressions, or test failures.
109See the [developer notes](doc/developer-notes.md#commit-structure-for-tests)
110for guidance on where test coverage belongs in a commit stack.
111
112Commit messages should be verbose by default consisting of a short subject line
113(50 chars max), a blank line and detailed explanatory text as separate
114paragraph(s), unless the title alone is self-explanatory (like "Correct typo
115in init.cpp") in which case a single title line is sufficient. Commit messages should be
116helpful to people reading your code in the future, so explain the reasoning for
117your decisions. Further explanation [here](https://cbea.ms/git-commit/).
118
119If a particular commit references another issue, please add the reference. For
120example: `refs #1234` or `fixes #4321`. Using the `fixes` or `closes` keywords
121will cause the corresponding issue to be closed when the pull request is merged.
122
123Commit messages should never contain any `@` mentions (usernames prefixed with "@").
124
125Please refer to the [Git manual](https://git-scm.com/doc) for more information
126about Git.
127
128  - Push changes to your fork
129  - Create pull request
130
131### Creating the Pull Request
132
133The title of the pull request should be prefixed by the component or area that
134the pull request affects. Valid areas are:
135
136  - `consensus` for changes to consensus critical code
137  - `doc` for changes to the documentation
138  - `qt` or `gui` for changes to bitcoin-qt
139  - `log` for changes to log messages
140  - `mining` for changes to the mining code
141  - `net` or `p2p` for changes to the peer-to-peer network code
142  - `refactor` for structural changes that do not change behavior
143  - `rpc`, `rest` or `zmq` for changes to the RPC, REST or ZMQ APIs
144  - `contrib` or `cli` for changes to the scripts and tools
145  - `test`, `qa` or `ci` for changes to the unit tests, QA tests or CI code
146  - `util` or `lib` for changes to the utils or libraries
147  - `wallet` for changes to the wallet code
148  - `build` for changes to CMake
149  - `guix` for changes to the GUIX reproducible builds
150
151Examples:
152
153    consensus: Add new opcode for BIP-XXXX OP_CHECKAWESOMESIG
154    net: Automatically create onion service, listen on Tor
155    qt: Add feed bump button
156    log: Fix typo in log message
157
158The body of the pull request should contain sufficient description of *what* the
159patch does, and even more importantly, *why*, with justification and reasoning.
160You should include references to any discussions (for example, other issues or
161mailing list discussions).
162
163The description for a new pull request should not contain any `@` mentions. The
164PR description will be included in the commit message when the PR is merged and
165any users mentioned in the description will be annoyingly notified each time a
166fork of Bitcoin Core copies the merge. Instead, make any username mentions in a
167subsequent comment to the PR.
168
169### Translation changes
170
171Note that translations should not be submitted as pull requests. Please see
172[Translation Process](/doc/translation_process.md)
173for more information on helping with translations.
174
175### Work in Progress Changes and Requests for Comments
176
177If a pull request is not to be considered for merging (yet), please
178prefix the title with [WIP] or use [Tasks Lists](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#task-lists)
179in the body of the pull request to indicate tasks are pending.
180
181### Address Feedback
182
183At this stage, one should expect comments and review from other contributors. You
184can add more commits to your pull request by committing them locally and pushing
185to your fork.
186
187You are expected to reply to any review comments before your pull request is
188merged. You may update the code or reject the feedback if you do not agree with
189it, but you should express so in a reply. If there is outstanding feedback and
190you are not actively working on it, your pull request may be closed.
191
192Please refer to the [peer review](#peer-review) section below for more details.
193
194### Squashing Commits
195
196If your pull request contains fixup commits (commits that change the same line of code repeatedly) or too fine-grained
197commits, you may be asked to [squash](https://git-scm.com/docs/git-rebase#_interactive_mode) your commits
198before it will be reviewed. The basic squashing workflow is shown below.
199
200    git checkout your_branch_name
201    git rebase -i HEAD~n
202    # n is normally the number of commits in the pull request.
203    # Set commits (except the one in the first line) from 'pick' to 'squash', save and quit.
204    # On the next screen, edit/refine commit messages.
205    # Save and quit.
206    git push -f # (force push to GitHub)
207
208Please update the resulting commit message, if needed. It should read as a
209coherent message. In most cases, this means not just listing the interim
210commits.
211
212If your change contains a merge commit, the above workflow may not work and you
213will need to remove the merge commit first. See the next section for details on
214how to rebase.
215
216Please refrain from creating several pull requests for the same change.
217Use the pull request that is already open (or was created earlier) to amend
218changes. This preserves the discussion and review that happened earlier for
219the respective change set.
220
221The length of time required for peer review is unpredictable and will vary from
222pull request to pull request.
223
224### Rebasing Changes
225
226When a pull request conflicts with the target branch, you may be asked to rebase it on top of the current target branch.
227
228    git fetch https://github.com/bitcoin/bitcoin  # Fetch the latest upstream commit
229    git rebase FETCH_HEAD  # Rebuild commits on top of the new base
230
231This project aims to have a clean git history, where code changes are only made in non-merge commits. This simplifies
232auditability because merge commits can be assumed to not contain arbitrary code changes. Merge commits should be signed,
233and the resulting git tree hash must be deterministic and reproducible. The script in
234[/contrib/verify-commits](/contrib/verify-commits) checks that.
235
236After a rebase, reviewers are encouraged to sign off on the force push. This should be relatively straightforward with
237the `git range-diff` tool explained in the [productivity
238notes](/doc/productivity.md#diff-the-diffs-with-git-range-diff). To avoid needless review churn, maintainers will
239generally merge pull requests that received the most review attention first.
240
241Pull Request Philosophy
242-----------------------
243
244Patchsets should always be focused. For example, a pull request could add a
245feature, fix a bug, or refactor code; but not a mixture. Please also avoid super
246pull requests which attempt to do too much, are overly large, or overly complex
247as this makes review difficult.
248
249
250### Features