Add JS and Python style guides to policies

docs/contributing/source/conf.py

@@ -15,7 +15,7 @@
 
 import wget # is for real!
 
-from os import rename
+from os import rename, remove
 from recommonmark.parser import CommonMarkParser
 
 # If extensions (or modules to document with autodoc) are in another directory,
@@ -44,17 +44,37 @@ extensions = [
 # Get remote files to here.
 # Because this is just Pyton and we can do whatever Python can do:
 
-url1 = 'https://raw.githubusercontent.com/bigchaindb/bigchaindb/master/CODE_OF_CONDUCT.md'
-filename1 = wget.download(url1)
-rename('CODE_OF_CONDUCT.md', 'cross-project-policies/code-of-conduct.md')
+try:
+    remove('cross-project-policies/code-of-conduct.md')
+    remove('cross-project-policies/shared-workspace.md')
+    remove('cross-project-policies/release-process.md')
+    remove('cross-project-policies/python-style-guide.md')
+    remove('cross-project-policies/js-style-guide.md')
+except:
+    print('done')
+
+def get_old_new(url, old, new):
+    filename = wget.download(url)
+    rename(old, new)
+
+get_old_new('https://raw.githubusercontent.com/bigchaindb/bigchaindb/master/CODE_OF_CONDUCT.md',
+            'CODE_OF_CONDUCT.md', 'cross-project-policies/code-of-conduct.md')
+
+get_old_new('https://raw.githubusercontent.com/vrde/bigchaindb-org/16b503b7c34e64f96aaccaefc4c826492174a5ae/protocols/shared-workspace.md',
+            'shared-workspace.md', 'cross-project-policies/shared-workspace.md')
+
+get_old_new('https://raw.githubusercontent.com/bigchaindb/bigchaindb/master/RELEASE_PROCESS.md',
+            'RELEASE_PROCESS.md', 'cross-project-policies/release-process.md')
+
+get_old_new('https://raw.githubusercontent.com/bigchaindb/bigchaindb/master/PYTHON_STYLE_GUIDE.md',
+            'PYTHON_STYLE_GUIDE.md', 'cross-project-policies/python-style-guide.md')
+
+get_old_new('https://raw.githubusercontent.com/ascribe/javascript/master/README.md',
+            'README.md','cross-project-policies/js-style-guide.md')
+
+suppress_warnings = ['misc.highlighting_failure']
 
-url2 = 'https://raw.githubusercontent.com/vrde/bigchaindb-org/16b503b7c34e64f96aaccaefc4c826492174a5ae/protocols/shared-workspace.md'
-filename2 = wget.download(url2)
-rename('shared-workspace.md', 'cross-project-policies/shared-workspace.md')
 
-url3 = 'https://raw.githubusercontent.com/bigchaindb/bigchaindb/master/RELEASE_PROCESS.md'
-filename3 = wget.download(url3)
-rename('RELEASE_PROCESS.md', 'cross-project-policies/release-process.md')
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

docs/contributing/source/cross-project-policies/index.rst

@@ -7,6 +7,7 @@ Policies
 
    code-of-conduct
    shared-workspace
-   release-process-note
+   python-style-guide
+   js-style-guide
    release-process
    

docs/contributing/source/cross-project-policies/python-style-guide.md

@@ -0,0 +1,90 @@
+# 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.5+, so you can ignore all PEP8 guidelines specific to Python 2.
+
+We use [pre-commit](http://pre-commit.com/) to check some of the rules below before every commit but not everything is realized yet.
+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.
+
+### 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.) As a hard limit, keep all lines less than 119 characters (which is the width of GitHub code review).
+
+### 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.)
+
+### How to Format Long import Statements
+
+If you need to `import` lots of names from a module or package, and they won't all fit in one line (without making the line too long), then use parentheses to spread the names across multiple lines, like so:
+```python
+from Tkinter import (
+    Tk, Frame, Button, Entry, Canvas, Text,
+    LEFT, DISABLED, NORMAL, RIDGE, END,
+)
+
+# Or
+
+from Tkinter import (Tk, Frame, Button, Entry, Canvas, Text,
+                     LEFT, DISABLED, NORMAL, RIDGE, END)
+```
+
+For the rationale, see [PEP 328](https://www.python.org/dev/peps/pep-0328/#rationale-for-parentheses).
+
+### 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. 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."
+
+
+## Running the Flake8 Style Checker
+
+We use [Flake8](http://flake8.pycqa.org/en/latest/index.html) to check our Python code style. Once you have it installed, you can run it using:
+```text
+flake8 --max-line-length 119 bigchaindb/
+```
+
+
+## Writing and Running (Python) Tests
+
+The content of this section was moved to [`bigchaindb/tests/README.md`](./tests/README.md).
+
+Note: We automatically run all tests on all pull requests (using Travis CI), so you should definitely run all tests locally before you submit a pull request. See the above-linked README file for instructions.

docs/contributing/source/cross-project-policies/release-process-note.md

@@ -1,9 +0,0 @@
-# Notes on Our Release Process
-
-"Our Release Process" is our release process for BigchainDB Server, not something else.
-
-It hasn't been revised for [C4](https://github.com/bigchaindb/BEPs/tree/master/1) yet. It should be. That will simplify it a lot. Releases are just tags on the ``master`` branch. There are no topic branches!
-
-Minor releases (X.Y.Z) and major releases (X.Y) are all just Git tags (named commits). There are no branches.
-
-What if 2.4 is out but now you want to release an update to 2.3.1 named 2.3.2? Easy, create a whole new repository and let the `master` branch over in that repository represent the 2.3.x history.

docs/contributing/source/cross-project-policies/release-process.md

@@ -1,5 +1,13 @@
 # Our Release Process
 
+## Notes
+
+This process hasn't been updated to the C4 way yet. That will simplify it a lot. Stay tuned! Until then, the basic idea is that there's only one branch: `master`. All releases are just Git tags of specific commits on the `master` branch.
+
+This is the _BigchainDB Server_ release process. The process to release other BigchainDB software will be similar but not identical.
+
+<hr>
+
 The release process for BigchainDB server differs slightly depending on whether it's a minor or a patch release.
 
 BigchainDB follows 

docs/contributing/source/ways-can-contribute/vanshdeep-notes.md

@@ -149,7 +149,7 @@ $ docker-compose -f docker-compose.travis.yml run --rm --no-deps bdb pytest -v -
 NOTE: before executing the above command the user must ensure that they reset the Tendermint container by executing `tendermint usafe_reset_all` command in the Tendermint container.
 
 
-### Notes
+### Closing Notes
 
 How to check `bigchaindb upsert-validator`: