CONTRIBUTING.md 12 KB
Newer Older
1
# Contributing to Bitcoin Cash Node
BtcDrak's avatar
BtcDrak committed
2

3
The Bitcoin Cash Node project welcomes contributors!
BtcDrak's avatar
BtcDrak committed
4

5 6
This guide is intended to help developers and others contribute effectively
to Bitcoin Cash Node.
7

8

9
## Communicating with the project
10

11 12
To get in contact with the Bitcoin Cash Node project, we monitor a number
of resources.
13

14
Our main development repository is currently located at
15

16
[https://gitlab.com/bitcoin-cash-node/bitcoin-cash-node](https://gitlab.com/bitcoin-cash-node/bitcoin-cash-node)
17 18 19 20 21 22

This features the project code, an issue tracker and facilities to see
project progress and activities, even in detailed form such as individual
change requests.

Users are free to submit issues or comment on existing ones - all that is
23 24
needed is a GitLab account which can be freely registered (use the 'Register'
button on the GitLab page).
25 26 27 28

In addition to the project repository, we have various other channels where
project contributors can be reached.

29
Our main chat is at <https://bitcoincashnode.slack.com>, where we conduct
30 31 32 33 34
our main development and interactive support for users of our node.

Other social media resources such as our Telegram and Twitter are linked
from the project website at

35
[https://bitcoincashnode.org](https://bitcoincashnode.org)
36 37 38 39 40 41 42 43 44

On all our channels, we seek to facilitate development of Bitcoin Cash Node,
and to welcome and support people who wish to participate.

Please visit our channels to

* Introduce yourself to other Bitcoin Cash Node contributors
* Get help with your development environment
* Discuss how to complete a patch.
45 46 47 48 49

It is not for:

* Market discussion
* Non-constructive criticism
50

51
## Bitcoin Cash Node Development Philosophy
52

53
Bitcoin Cash Node aims for fast iteration and continuous integration.
54 55 56 57

This means that there should be quick turnaround for patches to be proposed,
reviewed, and committed. Changes should not sit in a queue for long.

58 59
### Expectations of contributors

60
Here are some tips to help keep the development working as intended. These
Dagur's avatar
Dagur committed
61 62
are guidelines for the normal and expected development process. Developers
can use their judgement to deviate from these guidelines when they have a
63
good reason to do so.
64

65
- Keep each change minimal and self-contained.
66 67
- Don't amend a Merge Request after it has been accepted for merging unless
  with coordination with the maintainer(s)
68 69 70 71 72 73 74 75
- Large changes should be broken into logical chunks that are easy to review,
and keep the code in a functional state.
- Do not mix moving stuff around with changing stuff. Do changes with renames
on their own.
- Sometimes you want to replace one subsystem by another implementation,
in which case it is not possible to do things incrementally. In such cases,
you keep both implementations in the codebase for a while, as described
[here](https://www.gamasutra.com/view/news/128325/Opinion_Parallel_Implementations.php)
76
- There are no "development" branches, all merge requests apply to the master
77
branch, and should always improve it (no regressions).
78 79
- As soon as you see a bug, you fix it. Do not continue on. Fixing the bug
  becomes the top priority, more important than completing other tasks.
80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114

Note: Code review is a burdensome but important part of the development process,
and as such, certain types of merge requests are rejected. In general, if the
improvements do not warrant the review effort required, the MR has a high
chance of being rejected. Before working on a large or complex code change,
it is recommended to consult with project maintainers about the desirability
of the change, so you can be sure they are willing to spend the time required
to review your work.

#### Critical code paths

Some code paths are more critical than others. This applies to code such as
consensus, block template creation, mempool, relay policies and more. *Changes
to critical code paths really should inspire confidence*. The following things
can help inspire confidence:

- Minimal, easily reviewable merge requests.
- Extensive unit and/or functional tests.
- Patience for reviewers
- Appreciation for reviews.

### Expectations of maintainers

These are guidelines for the normal and expected process for handling merge
requests. Maintainers can use their judgement to deviate from these guidelines
when they have a good reason to do so.

- Try to guide contributors towards the goal of having their contributions
  merged.
- Identify whether the intent of an MR is desirable, independent of its
  technical quality.
- Merge accepted changes quickly after they are accepted.
- If a merge has been done and breaks the build of master, fix it quickly. If
  it cannot be fixed quickly, revert it. It can be re-applied later when it no
  longer breaks the build.
115
- Automate as much as possible, and spend time on things only humans can do.
116 117 118
- Speak up or raise an issue if you anticipate a problem with a change.
- Don't be afraid to say "NO", or "MAYBE, but...", if a change seems
  undesirable or if you otherwise have reservations/caveats/etc.
119

120
Here are some handy links for development practices aligned with Bitcoin Cash Node:
121

122
- [BCHN GitLab development working rules and guidelines](doc/bchn-gitlab-usage-rules-and-guidelines.md)
123
- [Developer Notes](doc/developer-notes.md)
124
- [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
Dagur's avatar
Dagur committed
125
- [How to Do Code Reviews Like a Human - Part 1](https://mtlynch.io/human-code-reviews-1/)
126
- [How to Do Code Reviews Like a Human - Part 2](https://mtlynch.io/human-code-reviews-2/)
127 128 129 130
- [Large Diffs Are Hurting Your Ability To Ship](https://medium.com/@kurtisnusbaum/large-diffs-are-hurting-your-ability-to-ship-e0b2b41e8acf)
- [Parallel Implementations](https://www.gamasutra.com/view/news/128325/Opinion_Parallel_Implementations.php)
- [The Pragmatic Programmer: From Journeyman to Master](https://www.amazon.com/Pragmatic-Programmer-Journeyman-Master/dp/020161622X)
- [Advantages of monolithic version control](https://danluu.com/monorepo/)
Mengerian's avatar
Mengerian committed
131
- [The importance of fixing bugs immediately](https://youtu.be/E2MIpi8pIvY?t=16m0s)
132
- [Good Work, Great Work, and Right Work](https://forum.dlang.org/post/q7u6g1$94p$1@digitalmars.com)
133
- [Accelerate: The Science of Lean Software and DevOps](https://www.amazon.com/Accelerate-Software-Performing-Technology-Organizations/dp/1942788339)
134

135 136

Getting set up with the Bitcoin Cash Node Repository
137 138
----------------------------------------------

139 140
1. Create an account at [https://gitlab.com](https://gitlab.com) if you don't have
   one yet
141
2. Install Git on your machine
142
    - Git documentation can be found at: [https://git-scm.com](https://git-scm.com)
143 144
    - To install these packages on Debian or Ubuntu,
      type: `sudo apt-get install git`
145
3. If you do not already have an SSH key set up, follow these steps:
146
    - Type: `ssh-keygen -t rsa -b 4096 -C "your_email@example.com"`
147 148 149 150
    - Enter a file in which to save the key
      (/home/*username*/.ssh/id_rsa): [Press enter]
    - *NOTE: the path in the message shown above is specific to UNIX-like systems
      and may differ if you run on other platforms.*
151
4. Upload your SSH public key to GitLab
152 153 154
    - Go to: [https://gitlab.com](https://gitlab.com), log in
    - Under "User Settings", "SSH Keys", add your public key
    - Paste contents from: `$HOME/.ssh/id_rsa.pub`
155
5. Create a personal fork of the Bitcoin Cash Node repository for your work
156
    - Sign into GitLab under your account, then visit the project at [https://gitlab.com/bitcoin-cash-node/bitcoin-cash-node](https://gitlab.com/bitcoin-cash-node/bitcoin-cash-node)
157 158
    - Click the 'Fork' button on the top right, and choose to fork the project to
      your personal GitLab space.
159 160
6. Clone your personal work repository to your local machine:

161 162 163
    ```
    git clone git@gitlab.com:username/bitcoin-cash-node.git
    ```
164 165 166

7. Set your checked out copy's upstream to our main project:

167 168 169
    ```
    git remote add upstream https://gitlab.com/bitcoin-cash-node/bitcoin-cash-node.git
    ```
170

171
8. You may want to add the `mreq` alias to your `.git/config`:
172

173 174 175 176
    ```
    [alias]
    mreq = !sh -c 'git fetch $1 merge-requests/$2/head:mr-$1-$2 && git checkout mr-$1-$2' -
    ```
177

178 179 180
    This `mreq` alias can be used to easily check out Merge Requests from our
    main repository if you intend to test them or work on them.
    Example:
181

182 183 184
    ```
    $ git mreq upstream 93
    ```
185

186 187
    This will checkout `merge-requests/93/head` and put you in a branch called `mr-origin-93`.
    You can then proceed to test the changes proposed by that merge request.
188

189
9. Code formatting tools
190

191
    During submission of patches, our GitLab process may refused code that
192
is not styled according to our coding guidelines.
193

194
    To enforce Bitcoin Cash Node codeformatting standards, you may need to
195 196
install `clang-format-8`, `clang-tidy` (version >=8), `autopep8`, `flake8`,
`phpcs` and `shellcheck` on your system to format your code before submission
197
as a Merge Request.
198

199 200
    To install `clang-format-8` and `clang-tidy` on Ubuntu (>= 18.04+updates)
    or Debian (>= 10):
201

202 203 204
    ```
    sudo apt-get install clang-format-8 clang-tidy-8 clang-tools-8
    ```
Fabien's avatar
Fabien committed
205

206
    If not available in the distribution, `clang-format-8` and `clang-tidy` can be
207 208
    installed from [https://releases.llvm.org/download.html](https://releases.llvm.org/download.html)
    or [https://apt.llvm.org](https://apt.llvm.org).
Fabien's avatar
Fabien committed
209

210 211
    For example, for macOS:

212 213 214 215 216
    ```
    curl http://releases.llvm.org/8.0.0/clang+llvm-8.0.0-x86_64-apple-darwin.tar.xz | tar -xJv
    ln -s $PWD/clang+llvm-8.0.0-x86_64-apple-darwin/bin/clang-format /usr/local/bin/clang-format
    ln -s $PWD/clang+llvm-8.0.0-x86_64-apple-darwin/bin/clang-tidy /usr/local/bin/clang-tidy
    ```
217

218
    To install `autopep8`, `flake8` and `phpcs` on Ubuntu:
219

220 221 222
    ```
    sudo apt-get install python-autopep8 flake8 php-codesniffer shellcheck
    ```
223

224

225 226
Working with The Bitcoin Cash Node Repository
---------------------------------------------
227 228 229 230 231 232 233 234 235 236 237

A typical workflow would be:

- Create a topic branch in Git for your changes

    git checkout -b 'my-topic-branch'

- Make your changes, and commit them

    git commit -a -m 'my-commit'

238
- Push the topic branch to your GitLab repository
239

240
    git push -u origin my-topic-branch
241

242
- Then create a Merge Request (the GitLab equivalent of a Pull Request)
243
  from that branch in your personal repository. To do this, you need to
244
  sign in to GitLab, go to the branch and click the button which lets you
245 246
  create a Merge Request (you need to fill out at least title and description
  fields).
247

248
- Work with us on GitLab to receive review comments, going back to the
249 250 251
  'Make your changes' step above if needed to make further changes on your
  branch, and push them upstream as above. They will automatically appear
  in your Merge Request.
252

253 254 255 256 257
All Merge Requests should contain a commit with a test plan that details
how to test the changes. In all normal circumstances, you should build and
test your changes locally before creating a Merge Request.
A merge request should feature a specific test plan where possible, and
indicate which regression tests may need to be run.
258

259 260
If you have doubts about the scope of testing needed for your change,
please contact our developers and they will help you decide.
261

262
- For large changes, break them into several Merge Requests.
263

264 265 266 267
- If you are making numerous changes and rebuilding often, it's highly
  recommended to install `ccache` (re-run cmake if you install it
  later), as this will help cut your re-build times from several minutes to under
  a minute, in many cases.
268 269 270 271 272

What to work on
---------------

If you are looking for a useful task to contribute to the project, a good place
273
to start is the list of issues at [https://gitlab.com/bitcoin-cash-node/bitcoin-cash-node/-/issues](https://gitlab.com/bitcoin-cash-node/bitcoin-cash-node/-/issues)
BtcDrak's avatar
BtcDrak committed
274

275
Look for issues marked with a label 'good-first-issue'.
BtcDrak's avatar
BtcDrak committed
276

Andrew C's avatar
Andrew C committed
277 278 279
Copyright
---------

Mengerian's avatar
Mengerian committed
280 281 282
By contributing to this repository, you agree to license your work under the
MIT license unless specified otherwise in `contrib/debian/copyright` or at
the top of the file itself. Any work contributed where you are not the original
Andrew C's avatar
Andrew C committed
283
author must contain its license header with the original author(s) and source.
284 285 286 287

Disclosure Policy
-----------------

288
See [DISCLOSURE_POLICY](DISCLOSURE_POLICY.md).