1
0
mirror of https://github.com/bigchaindb/bigchaindb.git synced 2024-06-29 00:57:45 +02:00
bigchaindb/CONTRIBUTING.md

7.0 KiB

How to Contribute to the BigchainDB Project

There are many ways you can contribute to the BigchainDB project, some very easy and others more involved. We want to be friendly and welcoming to all potential contributors, so we ask that everyone involved abide by some simple guidelines outlined in our Code of Conduct.

Easy Ways to Contribute

The BigchainDB community has a Google Group and a Gitter chatroom. Our Community page has more information about those.

You can also follow us on Twitter @BigchainDB or read our blog on Medium.

If you want to file a bug report, suggest a feature, or ask a code-related question, please go to the bigchaindb/bigchaindb repository on GitHub and create a new Issue. (You will need a GitHub account (free).) Please describe the issue clearly, including steps to reproduce when it is a bug.

How to Contribute Code or Documentation

Step 0 - Prepare and Familiarize Yourself

To contribute code or documentation, you need a GitHub account.

Familiarize yourself with how we do coding and documentation in the BigchainDB project, including:

Note: We have a slight variation on the GitHub Flow: we call the default branch develop rather than master.

Step 1 - Fork bigchaindb on GitHub

In your web browser, go to the BigchainDB repository on GitHub and click the Fork button in the top right corner. This creates a new Git repository named bigchaindb in your GitHub account.

Step 2 - Clone Your Fork

(This only has to be done once.) In your local terminal, use Git to clone your bigchaindb repository to your local computer. Also add the original GitHub bigchaindb/bigchaindb repository as a remote named upstream (a convention):

git clone git@github.com:your-github-username/bigchaindb.git
cd bigchaindb
git add upstream git@github.com:bigchaindb/bigchaindb.git

Step 3 - Fetch and Merge the Latest from upstream/develop

Switch to the develop branch locally, fetch all upstream branches, and merge the just-fetched upstream/develop branch with the local develop branch:

git checkout develop
git fetch upstream
git merge upstream/develop

Step 4 - Create a New Branch for Each Bug/Feature

If your new branch is to fix a bug identified in a specific GitHub Issue with number ISSNO, then name your new branch bug/ISSNO/short-description-here. For example, bug/67/fix-leap-year-crash.

If your new branch is to add a feature requested in a specific GitHub Issue with number ISSNO, then name your new branch feat/ISSNO/short-description-here. For example, feat/135/blue-background-on-mondays.

Otherwise, please give your new branch a short, descriptive, all-lowercase name.

git checkout -b new-branch-name

Step 5 - Make Edits, git add, git commit

With your new branch checked out locally, make changes or additions to the code or documentation. Remember to:

As you go, git add and git commit your changes or additions, e.g.

git add new-or-changed-file-1
git add new-or-changed-file-2
git commit -m "Short description of new or changed things"

You will want to merge changes from upstream (i.e. the original repository) into your new branch from time to time, using something like:

git fetch upstream
git merge upstream/develop

Once you're done commiting a set of new things and you're ready to submit them for inclusion, please be sure to run all the tests (as per the instructions at the end of our Python Style Guide).

If your addition or change is substantial, then please add a line or two to the CHANGELOG.md file, following the guidelines given at the top of that file.

(When you submit your pull request [following the instructions below], we run all the tests automatically, so we will see if some are failing. If you don't know why some tests are failing, you can still submit your pull request, but be sure to note the failing tests and to ask for help with resolving them.)

Step 6 - Push Your New Branch to origin

Make sure you've commited all the additions or changes you want to include in your pull request. Then push your new branch to origin (i.e. your remote bigchaindb repository).

git push origin new-branch-name

Step 7 - Create a Pull Request

Go to the GitHub website and to your remote bigchaindb repository (i.e. something like https://github.com/your-user-name/bigchaindb).

See GitHub's documentation on how to initiate and send a pull request. Note that the destination repository should be bigchaindb/bigchaindb and the destination branch will be develop (usually, and if it's not, then we can change that if necessary).

If this is the first time you've submitted a pull request to BigchainDB, then you must read and accept the Contributor License Agreement (CLA) before we can merge your contributions. That can be found at https://www.bigchaindb.com/cla.

Once you accept and submit the CLA, we'll email you with further instructions. (We will send you a long random string to put in the comments section of your pull request, along with the text, "I have read and agree to the terms of the BigchainDB Contributor License Agreement.")

Someone will then merge your branch or suggest changes. If we suggsest changes, you won't have to open a new pull request, you can just push new code to the same branch (on origin) as you did before creating the pull request.

(Note: GitHub automatically links to CONTRIBUTING.md when a contributor creates an Issue or opens a Pull Request.)