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.
Or, are you interested in contributing full-time? BigchainDB is hiring. See here.
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.
We want you to feel like your contributions (pull requests) are welcome, but if you contribute something unnecessary, unwanted, or perplexing, then your experience may be unpleasant. Your pull request may sit gathering dust as everyone scratches their heads wondering what to do with it.
To prevent that situation, we ask that all pull requests should resolve, address, or fix an existing issue. If there is no existing issue, then you should create one first. That way there can be commentary and discussion first, and you can have a better idea of what to expect when you create a corresponding pull request.
When you submit a pull request, please mention the issue (or issues) that it resolves, e.g. "Resolves #123".
Exception: hotfixes and minor changes don't require a pre-existing issue, but please write a thorough pull request description.
To contribute code or documentation, you need a GitHub account.
Familiarize yourself with how we do coding and documentation in the BigchainDB project, including:
- our Python Style Guide
- how we write and run tests
- our documentation strategy (including in-code documentation)
- the GitHub Flow (workflow)
- semantic versioning
- Install RethinkDB Server
- Make sure you have Python 3.5+ (preferably in a virtualenv)
- Install BigchaindB Server's OS-level dependencies
- Make sure you have the latest Python 3 version of pip and setuptools
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.
(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 remote add upstream git@github.com:bigchaindb/bigchaindb.git
Switch to the master branch locally, fetch all upstream branches, and merge the just-fetched upstream/master branch with the local master branch:
git checkout master
git fetch upstream
git merge upstream/master
In order to use and run the source you just cloned from your fork, you need to install BigchainDB on your computer.
The core of BigchainDB is a Python module you can install using the standard Python packaging tools.
We highly suggest you use pip and virtualenv to manage your local development.
If you need more information on how to do that, refer to the Python Packaging User Guide to install pip and to create your first virtualenv.
Once you have pip installed and (optionally) you are in a virtualenv, go to the root of the repository (i.e. where the setup.py file is), and type:
pip install -e .[dev]
This will install the BigchainDB Python module, the CLI, and all the dependencies useful for contributing to the development of BigchainDB. How? Let's split the command down into its components:
pipis the Python command to install packagesinstalltells pip to use the install action-einstalls a project in editable mode.installs what's in the current directory[dev]adds some extra requirements to the installation. (If you are curious, opensetup.pyand look fordevin theextras_requiresection.)
Aside: An alternative to pip install -e .[dev] is python setup.py develop.
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
With your new branch checked out locally, make changes or additions to the code or documentation. Remember to:
- follow our Python Style Guide.
- write and run tests for any new or changed code. There's a README file in the
tests/folder about how to do that. - add or update documentation as necessary. Follow our documentation strategy.
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"
We use pre-commit which should be triggered with every commit. Some hooks will change files but others will give errors that needs to be fixed. Every time a hook is failing you need to add the changed files again. The hooks we use can be found in the .pre-commit-config.yaml file.
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/master
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 in the README file in the tests/ folder.
(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.)
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
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 master (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 suggest 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.
Before you submit a pull request, check that it meets these guidelines:
- The pull request should include tests.
- If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst.
- The pull request should work for Python 3.5, and pass the flake8 check. Check https://travis-ci.org/bigchaindb/bigchaindb-driver/pull_requests and make sure that the tests pass for all supported Python versions.
- Follow the pull request template while creating new PRs, the template will be visible to you when you create a new pull request.
Over time, your versions of the Python packages used by BigchainDB will get out of date. You can upgrade them using:
pip install --upgrade -e .[dev]
- BigchainDB Community links
- General GitHub Documentation
- Code of Conduct
- BigchainDB Licenses
- Contributor License Agreement
(Note: GitHub automatically links to CONTRIBUTING.md when a contributor creates an Issue or opens a Pull Request.)