Mirroristas/bigchaindb
2
0
Fork 0
mirror of https://github.com/bigchaindb/bigchaindb.git synced 2024-10-13 13:34:05 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1947 from bigchaindb/update-contributing-md-file-for-tendermint-branch

Browse Source 
Update the CONTRIBUTING.md file (on tendermint branch)
This commit is contained in:
Troy McConaghy 2017-12-11 16:38:52 +01:00 committed by GitHub
commit 8c0e28ee46
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 31 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

64
CONTRIBUTING.md
View File

@ -2,15 +2,9 @@
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](./CODE_OF_CONDUCT.md). 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](./CODE_OF_CONDUCT.md).
Or, are you interested in contributing full-time? BigchainDB is hiring. See [here](https://github.com/bigchaindb/org/blob/master/engjob.md).
## Easy Ways to Contribute ## Easy Ways to Contribute
The BigchainDB community has a Google Group and a Gitter chatroom. Our [Community page](https://www.bigchaindb.com/community) has more information about those. If you want to file a bug report or suggest a feature, please go to the `bigchaindb/bigchaindb` repository on GitHub and [create a new Issue](https://github.com/bigchaindb/bigchaindb/issues/new). (You will need a [GitHub account](https://github.com/signup/free) (free).) Please describe the issue clearly, including steps to reproduce it, if it's a bug.
You can also follow us on Twitter [@BigchainDB](https://twitter.com/BigchainDB) or read [our blog on Medium](https://medium.com/the-bigchaindb-blog).
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](https://github.com/bigchaindb/bigchaindb/issues/new). (You will need a [GitHub account](https://github.com/signup/free) (free).) Please describe the issue clearly, including steps to reproduce when it is a bug.
## How to Contribute Code or Documentation ## How to Contribute Code or Documentation
@ -34,24 +28,22 @@ Familiarize yourself with how we do coding and documentation in the BigchainDB p
* [how we write and run tests](./tests/README.md) * [how we write and run tests](./tests/README.md)
* [our documentation strategy](./docs/README.md) (including in-code documentation) * [our documentation strategy](./docs/README.md) (including in-code documentation)
* the GitHub Flow (workflow) * the GitHub Flow (workflow)
* [GitHub Guide: Understanding the GitHub Flow](https://guides.github.com/introduction/flow/) * [GitHub Guide: Understanding the GitHub Flow](https://guides.github.com/introduction/flow/)
* [Scott Chacon's blog post about GitHub Flow](http://scottchacon.com/2011/08/31/github-flow.html) * [Scott Chacon's blog post about GitHub Flow](http://scottchacon.com/2011/08/31/github-flow.html)
* [semantic versioning](http://semver.org/) * [semantic versioning](http://semver.org/)
### Step 2 - Install some Dependencies ### Step 2 - Install some Dependencies
* [Install RethinkDB Server](https://rethinkdb.com/docs/install/) Install MongoDB, Tendermint, and all of BigchainDB Server's dependencies. The [Quickstart page](https://docs.bigchaindb.com/projects/server/en/latest/quickstart.html) has some pointers. In fact, you could do everything in the Quickstart page short of installing BigchainDB with pip (since you will install from the source on GitHub), and you shouldn't run MongoDB or Tendermint yet.
* Make sure you have Python 3.5+ (preferably in a virtualenv)
* [Install BigchaindB Server's OS-level dependencies](https://docs.bigchaindb.com/projects/server/en/latest/appendices/install-os-level-deps.html)
* [Make sure you have the latest Python 3 version of pip and setuptools](https://docs.bigchaindb.com/projects/server/en/latest/appendices/install-latest-pip.html)
### Step 3 - Fork bigchaindb on GitHub ### Step 3 - Fork the bigchaindb/bigchaindb GitHub Repository
In your web browser, go to [the BigchainDB repository on GitHub](https://github.com/bigchaindb/bigchaindb) and click the `Fork` button in the top right corner. This creates a new Git repository named `bigchaindb` in _your_ GitHub account. In your web browser, go to [the bigchaindb/bigchaindb repository on GitHub](https://github.com/bigchaindb/bigchaindb) and click the `Fork` button in the top right corner. This creates a new Git repository named `bigchaindb` in _your_ GitHub account.
### Step 4 - Clone Your Fork ### Step 4 - 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): (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):
```text ```text
git clone git@github.com:your-github-username/bigchaindb.git git clone git@github.com:your-github-username/bigchaindb.git
cd bigchaindb cd bigchaindb
@ -61,6 +53,7 @@ git remote add upstream git@github.com:bigchaindb/bigchaindb.git
### Step 5 - Fetch and Merge the Latest from `upstream/master` ### Step 5 - Fetch and Merge the Latest from `upstream/master`
Switch to the `master` branch locally, fetch all `upstream` branches, and merge the just-fetched `upstream/master` branch with the local `master` branch: Switch to the `master` branch locally, fetch all `upstream` branches, and merge the just-fetched `upstream/master` branch with the local `master` branch:
```text ```text
git checkout master git checkout master
git fetch upstream git fetch upstream
@ -69,27 +62,28 @@ git merge upstream/master
### Step 6 - Install the Python module and the CLI ### Step 6 - Install the Python module and the CLI
In order to use and run the source you just cloned from your fork, you need to install BigchainDB on your computer. To use and run the source code 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](http://python-packaging-user-guide.readthedocs.org/en/latest/). The core of BigchainDB is a Python module you can install using the standard [Python packaging tools](http://python-packaging-user-guide.readthedocs.org/en/latest/).
We highly suggest you use `pip` and `virtualenv` to manage your local development. 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`](http://python-packaging-user-guide.readthedocs.org/en/latest/installing/#requirements-for-installing-packages) and to [create your first `virtualenv`](http://python-packaging-user-guide.readthedocs.org/en/latest/installing/#creating-virtual-environments). If you need more information on how to do that, refer to the *Python Packaging User Guide* to [install `pip`](http://python-packaging-user-guide.readthedocs.org/en/latest/installing/#requirements-for-installing-packages) and to [create your first `virtualenv`](http://python-packaging-user-guide.readthedocs.org/en/latest/installing/#creating-virtual-environments).
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: 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:
```text ```text
pip install -e .[dev] 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. This will install the `bigchaindb` Python module, the BigchainDB Server CLI, and all the dependencies useful for contributing to the development of BigchainDB.
How? Let's split the command down into its components: How? Let's split the command down into its components:
- `pip` is the Python command to install packages
- `install` tells pip to use the *install* action * `pip` is the Python command to install packages
- `-e` installs a project in [editable mode](https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs) * `install` tells pip to use the *install* action
- `.` installs what's in the current directory * `-e` installs a project in [editable mode](https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs)
- `[dev]` adds some [extra requirements](https://setuptools.readthedocs.io/en/latest/setuptools.html#declaring-extras-optional-features-with-their-own-dependencies) to the installation. (If you are curious, open `setup.py` and look for `dev` in the `extras_require` section.) * `.` installs what's in the current directory
* `[dev]` adds some [extra requirements](https://setuptools.readthedocs.io/en/latest/setuptools.html#declaring-extras-optional-features-with-their-own-dependencies) to the installation. (If you are curious, open `setup.py` and look for `dev` in the `extras_require` section.)
Aside: An alternative to `pip install -e .[dev]` is `python setup.py develop`. Aside: An alternative to `pip install -e .[dev]` is `python setup.py develop`.
### Step 7 - Create a New Branch for Each Bug/Feature ### Step 7 - 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 **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`.
@ -97,6 +91,7 @@ If your new branch is to **fix a bug** identified in a specific GitHub Issue wit
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`. 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. Otherwise, please give your new branch a short, descriptive, all-lowercase name.
```text ```text
git checkout -b new-branch-name git checkout -b new-branch-name
``` ```
@ -110,16 +105,18 @@ With your new branch checked out locally, make changes or additions to the code
* add or update documentation as necessary. Follow [our documentation strategy](./docs/README.md). * add or update documentation as necessary. Follow [our documentation strategy](./docs/README.md).
As you go, git add and git commit your changes or additions, e.g. As you go, git add and git commit your changes or additions, e.g.
```text ```text
git add new-or-changed-file-1 git add new-or-changed-file-1
git add new-or-changed-file-2 git add new-or-changed-file-2
git commit -m "Short description of new or changed things" git commit -m "Short description of new or changed things"
``` ```
We use [pre-commit](http://pre-commit.com/) 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.
We use [pre-commit](http://pre-commit.com/) which should be triggered with every commit. Some hooks will change files but others will give errors that need 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](https://github.com/bigchaindb/bigchaindb/blob/master/.pre-commit-config.yaml) file. The hooks we use can be found in the [.pre-commit-config.yaml](https://github.com/bigchaindb/bigchaindb/blob/master/.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: You will want to merge changes from upstream (i.e. the original repository) into your new branch from time to time, using something like:
```text ```text
git fetch upstream git fetch upstream
git merge upstream/master git merge upstream/master
@ -132,6 +129,7 @@ Once you're done commiting a set of new things and you're ready to submit them f
### Step 9 - Push Your New Branch to origin ### Step 9 - 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). 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).
```text ```text
git push origin new-branch-name git push origin new-branch-name
``` ```
@ -153,28 +151,28 @@ Someone will then merge your branch or suggest changes. If we suggest changes, y
Before you submit a pull request, check that it meets these guidelines: Before you submit a pull request, check that it meets these guidelines:
1. The pull request should include tests. 1. The pull request should include tests.
2. If the pull request adds functionality, the docs should be updated. Put 1. If the pull request adds functionality, the docs should be updated. Put
your new functionality into a function with a docstring, and add the your new functionality into a function with a docstring, and add the
feature to the list in README.rst. feature to the list in README.rst.
3. The pull request should work for Python 3.5, and pass the flake8 check. 1. The pull request should work for Python 3.5, and pass the flake8 check.
Check https://travis-ci.org/bigchaindb/bigchaindb-driver/pull_requests 1. Follow the pull request template when creating new PRs. The template will
and make sure that the tests pass for all supported Python versions. be inserted when you create a new pull request.
4. Follow the pull request template while creating new PRs, the template will
be visible to you when you create a new pull request.
### Tip: Upgrading All BigchainDB Dependencies ### Tip: Upgrading All BigchainDB Dependencies
Over time, your versions of the Python packages used by BigchainDB will get out of date. You can upgrade them using: Over time, your versions of the Python packages used by BigchainDB will get out of date. You can upgrade them using:
```text ```text
pip install --upgrade -e .[dev] pip install --upgrade -e .[dev]
``` ```
## Quick Links ## Quick Links
* [BigchainDB Community links](https://www.bigchaindb.com/community) * [BigchainDB chatroom on Gitter](https://gitter.im/bigchaindb/bigchaindb)
* [BigchainDB on Twitter](https://twitter.com/BigchainDB)
* [General GitHub Documentation](https://help.github.com/) * [General GitHub Documentation](https://help.github.com/)
* [Code of Conduct](./CODE_OF_CONDUCT.md) * [Code of Conduct](./CODE_OF_CONDUCT.md)
* [BigchainDB Licenses](./LICENSES.md) * [BigchainDB Licenses](./LICENSES.md)
* [Contributor License Agreement](https://www.bigchaindb.com/cla) * [Contributor License Agreement](https://www.bigchaindb.com/cla)
(Note: GitHub automatically links to CONTRIBUTING.md when a contributor creates an Issue or opens a Pull Request.) (Note: GitHub automatically links to this file [CONTRIBUTING.md] when a contributor creates a new issue or pull request.)