diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,7 +3,118 @@ The Bitcoin ABC project welcomes contributors! -To contribute, sign up at: https://reviews.bitcoinabc.org/ +This guide is intended to help developers get started contributing to Bitcoin ABC. + +Bitcoin ABC Development Philosophy +---------------------------------- + +Bitcoin ABC aims for fast iteration and continuous integration. + +This means that there should be quick turnaround for patches to be proposed, +reviewed, and committed. + +Here are some tips to help keep the development working as intended: + + - Keep each change small and self-contained. + - Land the Diff quickly after it is accepted. + - Review Diffs 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. + - There are no "development" branches, all Diffs apply to the Master + branch, and should always improve it (no regressions). + - Don't break the build, and immediately revert Diffs that do break it. + - 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: + + - [Statement of Bitcoin ABC Values and Visions](https://www.yours.org/content/bitcoin-abc---our-values-and-vision-a282afaade7c) + - [Large Diffs Are Hurting Your Ability To Ship](https://medium.com/@kurtisnusbaum/large-diffs-are-hurting-your-ability-to-ship-e0b2b41e8acf) + - [Advantages of monolithic version control](https://danluu.com/monorepo/) + - [Stacked Diffs: Keeping Phabricator Diffs Small](https://medium.com/@kurtisnusbaum/stacked-diffs-keeping-phabricator-diffs-small-d9964f4dcfa6) + - [The Pragmatic Programmer: From Journeyman to Master](https://www.amazon.com/Pragmatic-Programmer-Journeyman-Master/dp/020161622X) + + +Getting set up with the Bitcoin ABC Repository +---------------------------------------------- + +1. Create an account at https://reviews.bitcoinabc.org/ + +2. Install Git and Arcanist 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` + +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 + + - go to: `https://reviews.bitcoinabc.org/settings/user/*username*/page/ssh/` + + - Under "SSH Key Actions", Select "Upload Public Key" + +Paste contents from: `/home/*username*/.ssh/id_rsa.pub` + +5. Clone the repository and install Arcanist certificate: + +``` +git clone ssh://vcs@reviews.bitcoinabc.org:2221/source/bitcoin-abc.git + +cd bitcoin-abc + +arc install-certificate +``` + +Then paste an API token from: `https://reviews.bitcoinabc.org/settings/user/*username*/page/apitokens/` + +6. Code formatting tools + +If code formatting tools do not install automatically on your system, you +may have to install clang-format-3.8 and autopep8. + + +Working with Phabricator and Arcanist +------------------------------------- + +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'` + + - 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. + + - Log into Phabricator to see review and feedback. + + - 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, and squash the commits by typing `git rebase -i HEAD~2`. + If you Squash, make sure the most recent commit message has the information + needed for arcanist (such as the Diff number, reviewers, etc.). + + - 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 succesfully + committed a change to the Bitcoin ABC repository. Copyright @@ -13,3 +124,4 @@ 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 author must contain its license header with the original author(s) and source. +