Merge #11753: clarify abortrescan rpc use
[bitcoinplatinum.git] / CONTRIBUTING.md
blob8381bd2448959e37813821d30190c65e6806e356
1 Contributing to Bitcoin Core
2 ============================
4 The Bitcoin Core project operates an open contributor model where anyone is
5 welcome to contribute towards development in the form of peer review, testing
6 and patches. This document explains the practical process and guidelines for
7 contributing.
9 Firstly in terms of structure, there is no particular concept of "Core
10 developers" in the sense of privileged people. Open source often naturally
11 revolves around meritocracy where longer term contributors gain more trust from
12 the developer community. However, some hierarchy is necessary for practical
13 purposes. As such there are repository "maintainers" who are responsible for
14 merging pull requests as well as a "lead maintainer" who is responsible for the
15 release cycle, overall merging, moderation and appointment of maintainers.
18 Contributor Workflow
19 --------------------
21 The codebase is maintained using the "contributor workflow" where everyone
22 without exception contributes patch proposals using "pull requests". This
23 facilitates social contribution, easy testing and peer review.
25 To contribute a patch, the workflow is as follows:
27   1. Fork repository
28   1. Create topic branch
29   1. Commit patches
31 The project coding conventions in the [developer notes](doc/developer-notes.md)
32 must be adhered to.
34 In general [commits should be atomic](https://en.wikipedia.org/wiki/Atomic_commit#Atomic_commit_convention)
35 and diffs should be easy to read. For this reason do not mix any formatting
36 fixes or code moves with actual code changes.
38 Commit messages should be verbose by default consisting of a short subject line
39 (50 chars max), a blank line and detailed explanatory text as separate
40 paragraph(s), unless the title alone is self-explanatory (like "Corrected typo
41 in init.cpp") in which case a single title line is sufficient. Commit messages should be
42 helpful to people reading your code in the future, so explain the reasoning for
43 your decisions. Further explanation [here](http://chris.beams.io/posts/git-commit/).
45 If a particular commit references another issue, please add the reference. For
46 example: `refs #1234` or `fixes #4321`. Using the `fixes` or `closes` keywords
47 will cause the corresponding issue to be closed when the pull request is merged.
49 Please refer to the [Git manual](https://git-scm.com/doc) for more information
50 about Git.
52   - Push changes to your fork
53   - Create pull request
55 The title of the pull request should be prefixed by the component or area that
56 the pull request affects. Valid areas as:
58   - *Consensus* for changes to consensus critical code
59   - *Docs* for changes to the documentation
60   - *Qt* for changes to bitcoin-qt
61   - *Mining* for changes to the mining code
62   - *Net* or *P2P* for changes to the peer-to-peer network code
63   - *RPC/REST/ZMQ* for changes to the RPC, REST or ZMQ APIs
64   - *Scripts and tools* for changes to the scripts and tools
65   - *Tests* for changes to the bitcoin unit tests or QA tests
66   - *Trivial* should **only** be used for PRs that do not change generated
67     executable code. Notably, refactors (change of function arguments and code
68     reorganization) and changes in behavior should **not** be marked as trivial.
69     Examples of trivial PRs are changes to:
70     - comments
71     - whitespace
72     - variable names
73     - logging and messages
74   - *Utils and libraries* for changes to the utils and libraries
75   - *Wallet* for changes to the wallet code
77 Examples:
79     Consensus: Add new opcode for BIP-XXXX OP_CHECKAWESOMESIG
80     Net: Automatically create hidden service, listen on Tor
81     Qt: Add feed bump button
82     Trivial: Fix typo in init.cpp
84 Note that translations should not be submitted as pull requests, please see
85 [Translation Process](https://github.com/bitcoin/bitcoin/blob/master/doc/translation_process.md) 
86 for more information on helping with translations.
88 If a pull request is not to be considered for merging (yet), please
89 prefix the title with [WIP] or use [Tasks Lists](https://help.github.com/articles/basic-writing-and-formatting-syntax/#task-lists)
90 in the body of the pull request to indicate tasks are pending.
92 The body of the pull request should contain enough description about what the
93 patch does together with any justification/reasoning. You should include
94 references to any discussions (for example other tickets or mailing list
95 discussions).
97 At this stage one should expect comments and review from other contributors. You
98 can add more commits to your pull request by committing them locally and pushing
99 to your fork until you have satisfied all feedback.
101 Squashing Commits
102 ---------------------------
103 If your pull request is accepted for merging, you may be asked by a maintainer
104 to squash and or [rebase](https://git-scm.com/docs/git-rebase) your commits
105 before it will be merged. The basic squashing workflow is shown below.
107     git checkout your_branch_name
108     git rebase -i HEAD~n
109     # n is normally the number of commits in the pull
110     # set commits from 'pick' to 'squash', save and quit
111     # on the next screen, edit/refine commit messages
112     # save and quit
113     git push -f # (force push to GitHub)
115 If you have problems with squashing (or other workflows with `git`), you can
116 alternatively enable "Allow edits from maintainers" in the right GitHub
117 sidebar and ask for help in the pull request.
119 Please refrain from creating several pull requests for the same change.
120 Use the pull request that is already open (or was created earlier) to amend
121 changes. This preserves the discussion and review that happened earlier for
122 the respective change set.
124 The length of time required for peer review is unpredictable and will vary from
125 pull request to pull request.
128 Pull Request Philosophy
129 -----------------------
131 Patchsets should always be focused. For example, a pull request could add a
132 feature, fix a bug, or refactor code; but not a mixture. Please also avoid super
133 pull requests which attempt to do too much, are overly large, or overly complex
134 as this makes review difficult.
137 ### Features
139 When adding a new feature, thought must be given to the long term technical debt
140 and maintenance that feature may require after inclusion. Before proposing a new
141 feature that will require maintenance, please consider if you are willing to
142 maintain it (including bug fixing). If features get orphaned with no maintainer
143 in the future, they may be removed by the Repository Maintainer.
146 ### Refactoring
148 Refactoring is a necessary part of any software project's evolution. The
149 following guidelines cover refactoring pull requests for the project.
151 There are three categories of refactoring, code only moves, code style fixes,
152 code refactoring. In general refactoring pull requests should not mix these
153 three kinds of activity in order to make refactoring pull requests easy to
154 review and uncontroversial. In all cases, refactoring PRs must not change the
155 behaviour of code within the pull request (bugs must be preserved as is).
157 Project maintainers aim for a quick turnaround on refactoring pull requests, so
158 where possible keep them short, uncomplex and easy to verify.
160 Pull requests that refactor the code should not be made by new contributors. It
161 requires a certain level of experience to know where the code belongs to and to
162 understand the full ramification (including rebase effort of open pull requests).
164 Trivial pull requests or pull requests that refactor the code with no clear
165 benefits may be immediately closed by the maintainers to reduce unnecessary
166 workload on reviewing.
169 "Decision Making" Process
170 -------------------------
172 The following applies to code changes to the Bitcoin Core project (and related
173 projects such as libsecp256k1), and is not to be confused with overall Bitcoin
174 Network Protocol consensus changes.
176 Whether a pull request is merged into Bitcoin Core rests with the project merge
177 maintainers and ultimately the project lead.
179 Maintainers will take into consideration if a patch is in line with the general
180 principles of the project; meets the minimum standards for inclusion; and will
181 judge the general consensus of contributors.
183 In general, all pull requests must:
185   - Have a clear use case, fix a demonstrable bug or serve the greater good of
186     the project (for example refactoring for modularisation);
187   - Be well peer reviewed;
188   - Have unit tests and functional tests where appropriate;
189   - Follow code style guidelines ([C++](doc/developer-notes.md), [functional tests](test/functional/README.md));
190   - Not break the existing test suite;
191   - Where bugs are fixed, where possible, there should be unit tests
192     demonstrating the bug and also proving the fix. This helps prevent regression.
194 Patches that change Bitcoin consensus rules are considerably more involved than
195 normal because they affect the entire ecosystem and so must be preceded by
196 extensive mailing list discussions and have a numbered BIP. While each case will
197 be different, one should be prepared to expend more time and effort than for
198 other kinds of patches because of increased peer review and consensus building
199 requirements.
202 ### Peer Review
204 Anyone may participate in peer review which is expressed by comments in the pull
205 request. Typically reviewers will review the code for obvious errors, as well as
206 test out the patch set and opine on the technical merits of the patch. Project
207 maintainers take into account the peer review when determining if there is
208 consensus to merge a pull request (remember that discussions may have been
209 spread out over GitHub, mailing list and IRC discussions). The following
210 language is used within pull-request comments:
212   - ACK means "I have tested the code and I agree it should be merged";
213   - NACK means "I disagree this should be merged", and must be accompanied by
214     sound technical justification (or in certain cases of copyright/patent/licensing
215     issues, legal justification). NACKs without accompanying reasoning may be
216     disregarded;
217   - utACK means "I have not tested the code, but I have reviewed it and it looks
218     OK, I agree it can be merged";
219   - Concept ACK means "I agree in the general principle of this pull request";
220   - Nit refers to trivial, often non-blocking issues.
222 Reviewers should include the commit hash which they reviewed in their comments.
224 Project maintainers reserve the right to weigh the opinions of peer reviewers
225 using common sense judgement and also may weight based on meritocracy: Those
226 that have demonstrated a deeper commitment and understanding towards the project
227 (over time) or have clear domain expertise may naturally have more weight, as
228 one would expect in all walks of life.
230 Where a patch set affects consensus critical code, the bar will be set much
231 higher in terms of discussion and peer review requirements, keeping in mind that
232 mistakes could be very costly to the wider community. This includes refactoring
233 of consensus critical code.
235 Where a patch set proposes to change the Bitcoin consensus, it must have been
236 discussed extensively on the mailing list and IRC, be accompanied by a widely
237 discussed BIP and have a generally widely perceived technical consensus of being
238 a worthwhile change based on the judgement of the maintainers.
240 ### Finding Reviewers
242 As most reviewers are themselves developers with their own projects, the review
243 process can be quite lengthy, and some amount of patience is required. If you find
244 that you've been waiting for a pull request to be given attention for several
245 months, there may be a number of reasons for this, some of which you can do something
246 about:
248   - It may be because of a feature freeze due to an upcoming release. During this time,
249     only bug fixes are taken into consideration. If your pull request is a new feature,
250     it will not be prioritized until the release is over. Wait for release.
251   - It may be because the changes you are suggesting do not appeal to people. Rather than
252     nits and critique, which require effort and means they care enough to spend time on your
253     contribution, thundering silence is a good sign of widespread (mild) dislike of a given change
254     (because people don't assume *others* won't actually like the proposal). Don't take
255     that personally, though! Instead, take another critical look at what you are suggesting
256     and see if it: changes too much, is too broad, doesn't adhere to the
257     [developer notes](doc/developer-notes.md), is dangerous or insecure, is messily written, etc.
258     Identify and address any of the issues you find. Then ask e.g. on IRC if someone could give
259     their opinion on the concept itself.
260   - It may be because your code is too complex for all but a few people. And those people
261     may not have realized your pull request even exists. A great way to find people who
262     are qualified and care about the code you are touching is the
263     [Git Blame feature](https://help.github.com/articles/tracing-changes-in-a-file/). Simply
264     find the person touching the code you are touching before you and see if you can find
265     them and give them a nudge. Don't be incessant about the nudging though.
266   - Finally, if all else fails, ask on IRC or elsewhere for someone to give your pull request
267     a look. If you think you've been waiting an unreasonably long amount of time (month+) for
268     no particular reason (few lines changed, etc), this is totally fine. Try to return the favor
269     when someone else is asking for feedback on their code, and universe balances out.
272 Release Policy
273 --------------
275 The project leader is the release manager for each Bitcoin Core release.
277 Copyright
278 ---------
280 By contributing to this repository, you agree to license your work under the 
281 MIT license unless specified otherwise in `contrib/debian/copyright` or at 
282 the top of the file itself. Any work contributed where you are not the original 
283 author must contain its license header with the original author(s) and source.