Skip to content

Commit

Permalink
[doc] Update CONTRIBUTING.md with Bitcoin Cash Node relevant information
Browse files Browse the repository at this point in the history
  • Loading branch information
@ftrader @sickpig
ftrader authored and sickpig committed Mar 13, 2020
1 parent 4b9518f commit 41f2204
Showing 1 changed file with 127 additions and 90 deletions.
217 changes: 127 additions & 90 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,34 +1,59 @@
Contributing to Bitcoin ABC
===========================
Contributing to Bitcoin Cash Node
=================================

The Bitcoin ABC project welcomes contributors!
The Bitcoin Cash Node project welcomes contributors!

This guide is intended to help developers contribute effectively to Bitcoin ABC.
This guide is intended to help developers and others contribute effectively
to Bitcoin Cash Node.

Communicating with Developers
-----------------------------

To get in contact with ABC developers, we monitor a telegram supergroup. The
intent of this group is specifically to facilitate development of Bitcoin-ABC,
and to welcome people who wish to participate.
Communicating with the project
------------------------------

https://t.me/joinchat/HCYr50mxRWjA2uLqii-psw
To get in contact with the Bitcoin Cash Node project, we monitor a number
of resources.

Acceptable use of this supergroup includes the following:
Our main development repository is currently located at

* Introducing yourself to other ABC developers.
* Getting help with your development environment.
* Discussing how to complete a patch.
https://gitlab.com/bitcoin-cash-node/bitcoin-cash-node

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
needed is a Gitlab account which can be freely registered (use the 'Register'
button on the Gitlab page).

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

Our main chat is at https://bitcoincashnode.slack.com, where we conduct
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

https://bitcoincashnode.org

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.

It is not for:

* Market discussion
* Non-constructive criticism

Bitcoin ABC Development Philosophy
----------------------------------
Bitcoin Cash Node Development Philosophy
----------------------------------------

Bitcoin ABC aims for fast iteration and continuous integration.
Bitcoin Cash Node aims for fast iteration and continuous integration.

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.
Expand All @@ -40,9 +65,9 @@ good reason to do so.

- Keep each change small and self-contained.
- Reach out for a 1-on-1 review so things move quickly.
- Land the Diff quickly after it is accepted.
- Don't amend changes after the Diff accepted, new Diff for another fix.
- Review Diffs from other developers as quickly as possible.
- Merge accepted changes quickly after they are accepted.
- Don't amend a Merge Request after it has been accepted for merging unless with coordination with the maintainer(s)
- Review merge requests from other developers as quickly as possible.
- 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
Expand All @@ -51,84 +76,104 @@ on their own.
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)
- There are no "development" branches, all Diffs apply to the master
- There are no "development" branches, all merge requests apply to the master
branch, and should always improve it (no regressions).
- Don't break the build, it is important to keep master green as much as possible.
If a Diff is landed, and breaks the build, fix it quickly. If it cannot be fixed
quickly, it should be reverted, and re-applied later when it no longer breaks the build.
- 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.
- Do not break the build, it is important to keep master green as much as possible.
If a merge has been done and breaks the build, fix it quickly. If it cannot be fixed
quickly, it should be reverted, and re-applied later when it no longer breaks the build.
- Automate as much as possible, and spend time on things only humans can do.

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

- [BCHN Gitlab development working rules and guidelines](doc/bchn-gitlab-usage-rules-and-guidelines.md)
- [Developer Notes](doc/developer-notes.md)
- [Statement of Bitcoin ABC Values and Visions](https://www.yours.org/content/bitcoin-abc---our-values-and-vision-a282afaade7c)
- [How to Do Code Reviews Like a Human - Part 1](https://mtlynch.io/human-code-reviews-1/)
- [How to Do Code Reviews Like a Human - Part 2](https://mtlynch.io/human-code-reviews-2/)
- [Large Diffs Are Hurting Your Ability To Ship](https://medium.com/@kurtisnusbaum/large-diffs-are-hurting-your-ability-to-ship-e0b2b41e8acf)
- [Stacked Diffs: Keeping Phabricator Diffs Small](https://medium.com/@kurtisnusbaum/stacked-diffs-keeping-phabricator-diffs-small-d9964f4dcfa6)
- [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/)
- [The importance of fixing bugs immediately](https://youtu.be/E2MIpi8pIvY?t=16m0s)
- [Slow Deployment Causes Meetings](https://www.facebook.com/notes/kent-beck/slow-deployment-causes-meetings/1055427371156793/)
- [Good Work, Great Work, and Right Work](https://forum.dlang.org/post/q7u6g1$94p$1@digitalmars.com)
- [Accelerate: The Science of Lean Software and DevOps](https://www.amazon.com/Accelerate-Software-Performing-Technology-Organizations/dp/1942788339)

Getting set up with the Bitcoin ABC Repository

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

1. Create an account at https://reviews.bitcoinabc.org/
1. Create an account at https://gitlab.com/ if you don't have one yet

2. Install Git and Arcanist on your machine
2. Install Git on your machine

Git documentation can be found at: https://git-scm.com/

Arcanist documentation can be found at:
https://secure.phabricator.com/book/phabricator/article/arcanist_quick_start/

And: https://secure.phabricator.com/book/phabricator/article/arcanist/

To install these packages on Debian or Ubuntu, type: `sudo apt-get install git arcanist`
To install these packages on Debian or Ubuntu, type: `sudo apt-get install git`

3. If you do not already have an SSH key set up, follow these steps:

Type: `ssh-keygen -t rsa -b 4096 -C "your_email@example.com"`

Enter a file in which to save the key (/home/*username*/.ssh/id_rsa): [Press enter]

4. Upload your SSH public key to reviews.bitcoinabc.org
*NOTE: the path in the message shown above is specific to UNIX-like systems and may differ if you run on other platforms.*

4. Upload your SSH public key to Gitlab

- Go to: `https://gitlab.com, log in

- Go to: `https://reviews.bitcoinabc.org/settings/user/*username*/page/ssh/`
- Under "User Settings", "SSH Keys", add your public key

- Under "SSH Key Actions", Select "Upload Public Key"
Paste contents from: `$HOME/.ssh/id_rsa.pub`

Paste contents from: `/home/*username*/.ssh/id_rsa.pub`
5. Create a personal fork of the Bitcoin Cash Node repository for your work

5. Clone the repository and install Arcanist certificate:
- Sign into Gitlab under your account, then visit the project at https://gitlab.com/bitcoin-cash-node/bitcoin-cash-node

- Click the 'Fork' button on the top right, and choose to fork the project to your personal Gitlab space.

6. Clone your personal work repository to your local machine:

```
git clone git@gitlab.com:username/bitcoin-cash-node.git
```

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

```
git remote add upstream https://gitlab.com/bitcoin-cash-node/bitcoin-cash-node.git
```

8. You may want to add the 'mr' alias to your .git/config:

```
git clone ssh://vcs@reviews.bitcoinabc.org:2221/source/bitcoin-abc.git
[alias]
mr = !sh -c 'git fetch $1 merge-requests/$2/head:mr-$1-$2 && git checkout mr-$1-$2' -
```

This 'mr' alias can be used to easily check out Merge Requests from our
main repository if you intend to test them or work on them.

cd bitcoin-abc
Example:

arc install-certificate
```
$ git mr origin 93
```

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.

Note: Arcanist tooling will tend to fail if your remote origin is set to something other
than the above. A common mistake is to clone from Github and then forget to update
your remotes.

Follow instructions provided by `arc install-certificate` to provide your API token.
9. Code formatting tools

6. Code formatting tools
During submission of patches, our Gitlab process may refused code that
is not styled according to our coding guidelines.

During submission of patches, arcanist will automatically run `arc lint` to
enforce Bitcoin ABC code formatting standards, and often suggests changes.
If code formatting tools do not install automatically on your system, you
will have to install clang-format-8, clang-tidy (version >=8), autopep8, flake8,
phpcs and shellcheck.
To enforce Bitcoin Cash Node codeformatting standards, you may need to
install clang-format-8, clang-tidy (version >=8), autopep8, flake8,
phpcs and shellcheck on your system to format your code before submission
as a Merge Request.

To install clang-format-8 and clang-tidy on Ubuntu (>= 18.04+updates) or Debian (>= 10):
```
Expand All @@ -153,8 +198,8 @@ sudo apt-get install python-autopep8 flake8 php-codesniffer shellcheck
```


Working with The Bitcoin ABC Repository
---------------------------------------
Working with The Bitcoin Cash Node Repository
---------------------------------------------

A typical workflow would be:

Expand All @@ -166,52 +211,44 @@ A typical workflow would be:

git commit -a -m 'my-commit'

- Create a differential with Arcanist

arc diff

You should add suggested reviewers and a test plan to the commit message.
Note that Arcanist is set up to look only at the most-recent commit message,
So all you changes for this Diff should be in one Git commit.
- Push the topic branch to your Gitlab repository

- For large changes, break them into several Diffs, as described in this
[guide](https://medium.com/@kurtisnusbaum/stacked-diffs-keeping-phabricator-diffs-small-d9964f4dcfa6).
You can also include "Depends on Dxxx" in the Arcanist message to indicate
dependence on other Diffs.
git push -u origin my-topic-branch

- Log into Phabricator to see review and feedback.
- Then create a Merge Request (the Gitlab equivalent of a Pull Request)
from that branch in your personal repository. To do this, you need to
sign in to Gitlab, go to the branch and click the button which lets you
create a Merge Request (you need to fill out at least title and description
fields).

- Make changes as suggested by the reviewers. You can simply edit the files
with my-topic-branch checked out, and then type `arc diff`. Arcanist will
give you the option to add uncommited changes. Or, alternatively, you can
commit the changes using `git commit -a --am` to add them to the last commit,
or squash multiple commits by typing `git rebase -i master`. If you squash,
make sure the commit message has the information needed for arcanist (such
as the Diff number, reviewers, etc.).
- Work with us on Gitlab to receive review comments, going back to the
'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.

- Update your Diff by typing `arc diff` again.
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.

- When reviewers approve your Diff, it should be listed as "ready to Land"
in Phabricator. When you want to commit your diff to the repository, check out
type my-topic-branch in git, then type `arc land`. You have now successfully
committed a change to the Bitcoin ABC repository.
If you have doubts about the scope of testing needed for your change,
please contact our developers and they will help you decide.

- When reviewing a Diff, apply the changeset on your local by using
`arc patch D{NNNN}`
- For large changes, break them into several Merge Requests.

- You will likely be re-writing git histories multiple times, which causes
timestamp changes that require re-building a significant number of files. 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.
- 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.

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

If you are looking for a useful task to contribute to the project, a good place
to start is the list of tasks at https://reviews.bitcoinabc.org/maniphest/
to start is the list of issues at https://gitlab.com/bitcoin-cash-node/bitcoin-cash-node/-/issues

You could also try [backporting](doc/backporting.md) some code from Bitcoin Core.
Look for issues marked with a label 'good-first-issue'.

Copyright
---------
Expand Down

0 comments on commit 41f2204

Please sign in to comment.