Contributing to Bionic

Bionic’s source is maintained on GitHub. You can clone it with:

git clone git@github.com:square/bionic.git

Pull requests are welcome! (However, for large changes, we recommend discussing the proposed change on our Issues page first.) Because Bionic is supported by Square, all new contributors will be asked to sign Square’s Contributor License Agreement as part of the pull request process.

Setting Up Your Development Environment

Bionic has some additional dependencies required for running tests and building documentation. Most of these can be installed by running this from the root of the repo:

pip install -e .[dev]

If you want to build the documentation, you also need to install pandoc, which is used to convert notebook files into Sphinx documents. On OS X you can do this with Homebrew:

brew install pandoc

Running the Tests

Bionic uses pytest for tests and flake8 for linting. You can run them like this:

pytest
flake8

Travis should automatically run these for you when you submit a PR.

Pytest will skip the Google Cloud Storage tests unless you set an environment variable telling it which bucket to use:

BIONIC_TEST_GCS_BUCKET=my-bucket pytest

Updating the Documentation

Bionic’s documentation is built with Sphinx. You can build it from the docs directory:

make html

Alternatively, you can use sphinx-autobuild, which watches your document source files, automatically rebuilds them when they change, and runs a web server with the latest version:

make livehtml
# Leave this running and open localhost:8000 in your browser to see the docs.

Some of the documentation pages are built from Jupyter notebooks. When editing these, you need to remember two things:

  1. Don’t run any of the cells yourself; let Sphinx do that at build time. If you do run a cell, you can clear it with Edit > Clear All Outputs. If you leave any cell output in the notebook, Sphinx won’t try to run any of the cells itself.

  2. The “raw” text cells have special metadata that tells Sphinx that their contents are in the ReStructured Text format. As far as I know, this metadata can’t be changed by current versions of Jupyter Notebook or Jupyter Lab; you have to manually edit the .ipynb file. If you add any new text cells to a notebook, you’ll probably want to add this metadata as well.