Add Python Style Guide, update CONTRIBUTING.md

CONTRIBUTING.md

@@ -18,8 +18,8 @@ To contribute code or documentation, you need a [GitHub account](https://github.
 
 Familiarize yourself with how we do coding and documentation in the BigchainDB project, including:
 
-* our Python Style Guide (coming soon)
-* [our documentation strategy](./docs/README.md) (including code documentation)
+* [our Python Style Guide](PYTHON_STYLE_GUIDE.md) (includes how we write tests)
+* [our documentation strategy](./docs/README.md) (including in-code documentation)
 * the GitHub Flow (workflow)
     * [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)
@@ -63,27 +63,29 @@ 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, git add them, and git commit them.
+With your new branch checked out locally, make changes or additions to the code or documentation. Remember to:
+
+* follow [our Python Style Guide](PYTHON_STYLE_GUIDE.md).
+* write and run tests for any new or changed code. There's a section in [our Python Style Guide](PYTHON_STYLE_GUIDE.md) about writing and running tests.
+* 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.
 ```text
-git add new-or-changed-file
+git add new-or-changed-file-1
+git add new-or-changed-file-2
 git commit -m "Short description of new or changed things"
 ```
 
-Remember to write tests for new code. If you don't, our code (test) coverage will go down, and we won't be able to accept your code. (We have some hard checks that run on all new pull requests and code coverage is one of them.)
-
-Please run all existing tests to make sure you didn't break something. Do:
-```text
-py.test -v
-```
-
-Remember to write or modify documentation to reflect your additions or changes.
-
 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
 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](PYTHON_STYLE_GUIDE.md)).
+
+(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).

PYTHON_STYLE_GUIDE.md

@@ -0,0 +1,79 @@
+# Python Style Guide
+
+This guide starts out with our general Python coding style guidelines and ends with a section on how we write & run (Python) tests.
+
+## General Python Coding Style Guidelines
+
+Our starting point is [PEP8](https://www.python.org/dev/peps/pep-0008/), the standard "Style Guide for Python Code." Many Python IDEs will check your code against PEP8. (Note that PEP8 isn't frozen; it actually changes over time, but slowly.)
+
+BigchainDB uses Python 3.4+, so you can ignore all PEP8 guidelines specific to Python 2.
+
+### Python Docstrings
+
+PEP8 says some things about docstrings, but not what to put in them or how to structure them. [PEP257](https://www.python.org/dev/peps/pep-0257/) was one proposal for docstring conventions, but we prefer [Google-style docstrings](https://google.github.io/styleguide/pyguide.html?showone=Comments#Comments) instead: they're easier to read and the [napoleon extension](http://www.sphinx-doc.org/en/stable/ext/napoleon.html) for Sphinx lets us turn them into nice-looking documentation. Here are some references on Google-style docstrings:
+
+* [Google's docs on Google-style docstrings](https://google.github.io/styleguide/pyguide.html?showone=Comments#Comments)
+* [napoleon's docs include an overview of Google-style docstrings](http://sphinxcontrib-napoleon.readthedocs.org/en/latest/index.html)
+* [Example Google-style docstrings](http://sphinxcontrib-napoleon.readthedocs.org/en/latest/example_google.html) (from napoleon's docs)
+
+### Maximum Line Length
+
+PEP8 has some [maximum line length guidelines](https://www.python.org/dev/peps/pep-0008/#id17), starting with "Limit all lines to a maximum of 79 characters" but "for flowing long blocks of text with fewer structural restrictions (docstrings or comments), the line length should be limited to 72 characters."
+
+We discussed this at length, and it seems that the consensus is: try to keep line lengths less than 79/72 characters, unless you have a special situation where longer lines would improve readability. (The basic reason is that 79/72 works for everyone, and BigchainDB is an open source project.)
+
+### Single or Double Quotes?
+
+Python lets you use single or double quotes. PEP8 says you can use either, as long as you're consistent. We try to stick to using single quotes, except in cases where using double quotes is more readable. For example:
+```python
+print('This doesn\'t look so nice.')
+print("Doesn't this look nicer?")
+```
+
+### Breaking Strings Across Multiple Lines
+
+Should we use parentheses or slashes (`\`) to break strings across multiple lines, i.e.
+```python
+my_string = ('This is a very long string, so long that it will not fit into just one line '
+             'so it must be split across multiple lines.')
+# or
+my_string = 'This is a very long string, so long that it will not fit into just one line ' \
+            'so it must be split across multiple lines.'
+```
+
+It seems the preference is for slashes, but using parentheses is okay too. (There are good arguments either way. Arguing about it seems like a waste of time.)
+
+### Using the % operator or `format()` to Format Strings
+
+Given the choice:
+```python
+x = 'name: %s; score: %d' % (name, n)
+# or
+x = 'name: {}; score: {}'.format(name, n)
+```
+
+we use the `format()` version. It's newer and doesn't require you to remember a bunch of arcane markup.
+
+
+## Writing (Python) Tests
+
+We write 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.
+
+To run all the tests, first make sure you have RethinkDB running:
+```text
+$ rethinkdb
+```
+
+then in another terminal, do:
+```text
+$ py.test -v
+```
+
+If that doesn't work (e.g. maybe you are running in a conda virtual environment), try:
+```text
+$ python -m pytest -v
+```
+
+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.)