From 2a1892d1f7f8d439361fadc0cde33eaf143a0419 Mon Sep 17 00:00:00 2001 From: troymc Date: Tue, 12 Apr 2016 17:38:17 +0200 Subject: [PATCH 1/6] Docs: changed instructions for running unit tests --- docs/source/running-unit-tests.md | 18 +++++------------- 1 file changed, 5 insertions(+), 13 deletions(-) diff --git a/docs/source/running-unit-tests.md b/docs/source/running-unit-tests.md index 1a4f0e34..e20a0fc2 100644 --- a/docs/source/running-unit-tests.md +++ b/docs/source/running-unit-tests.md @@ -2,29 +2,21 @@ Once you've installed BigchainDB Server, you may want to run all the unit tests. This section explains how. -First of all, if you installed BigchainDB Server using `pip` (i.e. by getting the package from PyPI), then you didn't install the tests. Before you can run all the unit tests, you must [install BigchainDB from source](installing-server.html#how-to-install-bigchaindb-from-source). +First of all, if you installed BigchainDB Server using `pip` (i.e. by getting the package from PyPI), then you didn't install the tests. **Before you can run all the unit tests, you must [install BigchainDB from source](installing-server.html#how-to-install-bigchaindb-from-source).** To run all the unit tests, first make sure you have RethinkDB running: + ```text $ rethinkdb ``` then in another terminal, do: + ```text -$ py.test -v +$ python setup.py test ``` -If the above command doesn't work (e.g. maybe you are running in a conda virtual environment), try: -```text -$ python -m pytest -v -``` - -(We write our unit tests using the [pytest](http://pytest.org/latest/) framework.) - -You can also run all unit tests via `setup.py`, using: -```text -$ python setup.py test -``` +(Aside: How does the above command work? The documentation for [pytest-runner](https://pypi.python.org/pypi/pytest-runner) explains. We use [pytest](http://pytest.org/latest/) to write all unit tests.) ### Using docker-compose to Run the Tests From 70560408cddf53fc12240217fc7e84979eb6125a Mon Sep 17 00:00:00 2001 From: vrde Date: Wed, 13 Apr 2016 11:16:17 +0200 Subject: [PATCH 2/6] Add new step on how to install the package for dev --- CONTRIBUTING.md | 29 +++++++++++++++++++++++++---- 1 file changed, 25 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 65fdb205..4bccb7e8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -57,7 +57,28 @@ git fetch upstream git merge upstream/master ``` -### Step 5 - Create a New Branch for Each Bug/Feature +### Step 5 - Install the Python module an the CLI + +In order to use and run the source you just cloned from your fork, you need to install BigchainDB in 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/). +We highly suggest you to 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). + +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: +```bash +$ pip install -e .[dev] +``` + +This will install the BigchainDB Python module, the CLI, and all the dependencies useful to develop the project. +How? Let's split the command down into it's components: + - `pip` is the Python command to install packages + - `install` tells pip to use the *install* action + - `-e` installs a project in [editable mode](https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs) + - `.` installs what's in the current directory + - `[dev]` adds some [extra requirements](https://pythonhosted.org/setuptools/setuptools.html#declaring-extras-optional-features-with-their-own-dependencies) to the installation (if you are curious, open `setup.py` and check the `extras_require` section) + + +### Step 6 - 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`. @@ -68,7 +89,7 @@ Otherwise, please give your new branch a short, descriptive, all-lowercase name. git checkout -b new-branch-name ``` -### Step 6 - Make Edits, git add, git commit +### Step 7 - Make Edits, git add, git commit With your new branch checked out locally, make changes or additions to the code or documentation. Remember to: @@ -95,14 +116,14 @@ If your addition or change is substantial, then please add a line or two to the (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 7 - Push Your New Branch to origin +### Step 8 - 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). ```text git push origin new-branch-name ``` -### Step 8 - Create a Pull Request +### Step 9 - 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). From 4b4df442d57adce63d0e618147fb2ff424e4fb86 Mon Sep 17 00:00:00 2001 From: troymc Date: Wed, 13 Apr 2016 11:44:36 +0200 Subject: [PATCH 3/6] Developer-specific notes on running unit tests --- PYTHON_STYLE_GUIDE.md | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/PYTHON_STYLE_GUIDE.md b/PYTHON_STYLE_GUIDE.md index 536ed321..61863860 100644 --- a/PYTHON_STYLE_GUIDE.md +++ b/PYTHON_STYLE_GUIDE.md @@ -55,12 +55,27 @@ x = 'name: {}; score: {}'.format(name, n) we use the `format()` version. The [official Python documentation says](https://docs.python.org/2/library/stdtypes.html#str.format), "This method of string formatting is the new standard in Python 3, and should be preferred to the % formatting described in String Formatting Operations in new code." -## Writing (Python) Tests +## Writing and Running (Python) Unit Tests We write unit tests for our Python code using the [pytest](http://pytest.org/latest/) framework. All tests go in the `bigchaindb/tests` directory or one of its subdirectories. You can use the tests already in there as templates or examples. -The BigchainDB Documentation has a [section explaining how to run all unit tests](http://bigchaindb.readthedocs.org/en/master/running-unit-tests.html). +You can run all unit tests using: +```text +py.test -v +``` + +or, if that doesn't work, try: +```text +python -m pytest -v +``` + +or: +```text +python setup.py test +``` + +If you want to learn about all the things you can do with pytest, see [the pytest documentation](http://pytest.org/latest/). **Automated testing of pull requests.** We use [Travis CI](https://travis-ci.com/), so that whenever someone creates a new BigchainDB pull request on GitHub, Travis CI gets the new code and does _a bunch of stuff_. You can find out what we tell Travis CI to do in [the `.travis.yml` file](.travis.yml): it tells Travis CI how to install BigchainDB, how to run all the tests, and what to do "after success" (e.g. run `codecov`). (We use [Codecov](https://codecov.io/) to get a rough estimate of our test coverage.) From 44f6d832d72078b84007f825ec84d70e31738732 Mon Sep 17 00:00:00 2001 From: troymc Date: Wed, 13 Apr 2016 11:45:15 +0200 Subject: [PATCH 4/6] Minor edits to CONTRIBUTING.md --- CONTRIBUTING.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4bccb7e8..57b1d12f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -57,25 +57,25 @@ git fetch upstream git merge upstream/master ``` -### Step 5 - Install the Python module an the CLI +### Step 5 - 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 in your computer. +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](http://python-packaging-user-guide.readthedocs.org/en/latest/). -We highly suggest you to 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). -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: ```bash $ pip install -e .[dev] ``` -This will install the BigchainDB Python module, the CLI, and all the dependencies useful to develop the project. -How? Let's split the command down into it's components: +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: - `pip` is the Python command to install packages - `install` tells pip to use the *install* action - `-e` installs a project in [editable mode](https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs) - `.` installs what's in the current directory - - `[dev]` adds some [extra requirements](https://pythonhosted.org/setuptools/setuptools.html#declaring-extras-optional-features-with-their-own-dependencies) to the installation (if you are curious, open `setup.py` and check the `extras_require` section) + - `[dev]` adds some [extra requirements](https://pythonhosted.org/setuptools/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.) ### Step 6 - Create a New Branch for Each Bug/Feature From fd5cc287f11362268e4a554435af16bfa34b6118 Mon Sep 17 00:00:00 2001 From: troymc Date: Wed, 13 Apr 2016 11:55:25 +0200 Subject: [PATCH 5/6] Point developers to the installation instructions in CONTRIBUTING.md --- docs/source/installing-server.md | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/docs/source/installing-server.md b/docs/source/installing-server.md index 7da2b1c4..8d2be0ac 100644 --- a/docs/source/installing-server.md +++ b/docs/source/installing-server.md @@ -68,9 +68,9 @@ Note: You can use `pip` to upgrade the `bigchaindb` package to the latest versio ### How to Install BigchainDB from Source -BigchainDB (i.e. both the Server and the officially-supported drivers) is in its early stages and being actively developed on its [GitHub repository](https://github.com/bigchaindb/bigchaindb). Contributions are highly appreciated. If you want to help with development, then you'll want to install BigchainDB from source. Here's how. +If you want to install BitchainDB from source because you want to contribute code (i.e. as a BigchainDB developer), then please see the instructions in [the `CONTRIBUTING.md` file](https://github.com/bigchaindb/bigchaindb/blob/master/CONTRIBUTING.md). -First, clone the public repository: +Otherwise, clone the public repository: ```text $ git clone git@github.com:bigchaindb/bigchaindb.git ``` @@ -80,11 +80,6 @@ Install from the source: $ python setup.py install ``` -If you want to update BigchainDB to reflect the latest local source code changes, you can use: -```text -$ pip install -e . -``` - ### How to Install BigchainDB on a VM with Vagrant One of our community members ([@Mec-Is](https://github.com/Mec-iS)) wrote [a page about how to install BigchainDB on a VM with Vagrant](https://gist.github.com/Mec-iS/b84758397f1b21f21700). From 245cb9779d6f344eb3b8add48d5db6ffe4c85253 Mon Sep 17 00:00:00 2001 From: troymc Date: Wed, 13 Apr 2016 11:58:10 +0200 Subject: [PATCH 6/6] Minor docs edit --- docs/source/installing-server.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/installing-server.md b/docs/source/installing-server.md index 8d2be0ac..0d12a875 100644 --- a/docs/source/installing-server.md +++ b/docs/source/installing-server.md @@ -75,7 +75,7 @@ Otherwise, clone the public repository: $ git clone git@github.com:bigchaindb/bigchaindb.git ``` -Install from the source: +and then install from source: ```text $ python setup.py install ```