docs/source/development-guidelines.rst
This page is intended for developers of Zipline, people who want to contribute to the Zipline codebase or documentation, or people who want to install from source and make local changes to their copy of Zipline.
All contributions, bug reports, bug fixes, documentation improvements, enhancements and ideas are welcome. We track issues__ on GitHub__ and also have a mailing list__ where you can ask questions.
__ https://github.com/quantopian/zipline/issues __ https://github.com/ __ https://groups.google.com/forum/#!forum/zipline
First, you'll need to clone Zipline by running:
.. code-block:: bash
$ git clone [email protected]:your-github-username/zipline.git
Then check out to a new branch where you can make your changes:
.. code-block:: bash
$ git checkout -b some-short-descriptive-name
If you don't already have them, you'll need some C library dependencies. You can follow the install guide__ to get the appropriate dependencies.
__ install.html
Once you've created and activated a virtual environment__, run the etc/dev-install script to install all development dependencies in their required order:
__ https://docs.python.org/3/library/venv.html
.. code-block:: bash
$ python3 -m venv venv $ source venv/bin/activate $ etc/dev-install
Or, using virtualenvwrapper__:
__ https://virtualenvwrapper.readthedocs.io/en/latest/
.. code-block:: bash
$ mkvirtualenv zipline $ etc/dev-install
After installation, you should be able to use the zipline command line interface from your virtualenv:
.. code-block:: bash
$ zipline --help
To finish, make sure tests__ pass.
__ #style-guide-running-tests
If you get an error running nosetests after setting up a fresh virtualenv, please try running
.. code-block:: bash
$ deactivate zipline $ workon zipline
During development, you can rebuild the C extensions by running:
.. code-block:: bash
$ python setup.py build_ext --inplace
If you want to work with zipline using a Docker__ container, you'll need to build the Dockerfile in the Zipline root directory, and then build Dockerfile-dev. Instructions for building both containers can be found in Dockerfile and Dockerfile-dev, respectively.
__ https://docs.docker.com/get-started/
We use flake8__ for checking style requirements and nosetests__ to run Zipline tests. Our continuous integration__ tools will run these commands.
__ https://flake8.pycqa.org/en/latest/ __ https://nose.readthedocs.io/en/latest/ __ https://en.wikipedia.org/wiki/Continuous_integration
Before submitting patches or pull requests, please ensure that your changes pass when running:
.. code-block:: bash
$ flake8 zipline tests
In order to run tests locally, you'll need TA-lib__, which you can install on Linux by running:
__ https://mrjbq7.github.io/ta-lib/install.html
.. code-block:: bash
$ wget http://prdownloads.sourceforge.net/ta-lib/ta-lib-0.4.0-src.tar.gz $ tar -xvzf ta-lib-0.4.0-src.tar.gz $ cd ta-lib/ $ ./configure --prefix=/usr $ make $ sudo make install
And for TA-lib on OS X you can just run:
.. code-block:: bash
$ brew install ta-lib
Then run pip install TA-lib:
.. code-block:: bash
$ pip install -r ./etc/requirements_talib.in -c ./etc/requirements_locked.txt
You should now be free to run tests:
.. code-block:: bash
$ nosetests
We use Travis CI__ for Linux-64 bit builds and AppVeyor__ for Windows-64 bit builds.
.. note::
We do not currently have CI for OSX-64 bit builds. 32-bit builds may work but are not included in our integration tests.
__ https://travis-ci.org/quantopian/zipline __ https://ci.appveyor.com/project/quantopian/zipline
To learn about how we build Zipline conda packages, you can read this__ section in our release process notes.
__ release-process.html#uploading-conda-packages
If you update the zipline codebase so that it now depends on a new version of a library,
then you should update the lower bound on that dependency in etc/requirements.in
(or etc/requirements_dev.in as appropriate).
We use pip-compile__ to find mutually compatible versions of dependencies for the
etc/requirements_locked.txt lockfile used in our CI environments.
__ https://github.com/jazzband/pip-tools/
When you update a dependency in an .in file,
you need to re-run the pip-compile command included in the header of the lockfile__;
otherwise the lockfile will not meet the constraints specified to pip by zipline
at install time (via etc/requirements.in via setup.py).
__ https://github.com/quantopian/zipline/tree/master/etc/requirements_locked.txt
If the zipline codebase can still support an old version of a dependency, but you want
to update to a newer version of that library in our CI environments, then only the
lockfile needs updating. To update the lockfile without bumping the lower bound,
re-run the pip-compile command included in the header of the lockfile with the
addition of the --upgrade-package or -P flag__, e.g.
__ https://github.com/jazzband/pip-tools/#updating-requirements
.. code-block:: bash
$ pip-compile --output-file=etc/reqs.txt etc/reqs.in ... -P six==1.13.0 -P "click>4.0.0"
As you can see above, you can include multiple such constraints in a single invocation of pip-compile.
If you'd like to contribute to the documentation on zipline.io, you can navigate to docs/source/ where each reStructuredText__ (.rst) file is a separate section there. To add a section, create a new file called some-descriptive-name.rst and add some-descriptive-name to appendix.rst. To edit a section, simply open up one of the existing files, make your changes, and save them.
__ https://en.wikipedia.org/wiki/ReStructuredText
We use Sphinx__ to generate documentation for Zipline, which you will need to install by running:
__ https://www.sphinx-doc.org/en/master/
.. code-block:: bash
$ pip install -r ./etc/requirements_docs.in -c ./etc/requirements_locked.txt
If you would like to use Anaconda, please follow :ref:the installation guide<managing-conda-environments> to create and activate an environment, and then run the command above.
To build and view the docs locally, run:
.. code-block:: bash
$ cd docs $ make html $ {BROWSER} build/html/index.html
Standard prefixes to start a commit message:
.. code-block:: text
BLD: change related to building Zipline BUG: bug fix DEP: deprecate something, or remove a deprecated object DEV: development tool or utility DOC: documentation ENH: enhancement MAINT: maintenance commit (refactoring, typos, etc) REV: revert an earlier commit STY: style fix (whitespace, PEP8, flake8, etc) TST: addition or modification of tests REL: related to releasing Zipline PERF: performance enhancements
Some commit style guidelines:
Commit lines should be no longer than 72 characters__. The first line of the commit should include one of the above prefixes. There should be an empty line between the commit subject and the body of the commit. In general, the message should be in the imperative tense. Best practice is to include not only what the change is, but why the change was made.
__ https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project
Example:
.. code-block:: text
MAINT: Remove unused calculations of max_leverage, et al.
In the performance period the max_leverage, max_capital_used, cumulative_capital_used were calculated but not used.
At least one of those calculations, max_leverage, was causing a divide by zero error.
Instead of papering over that error, the entire calculation was a bit suspect so removing, with possibility of adding it back in later with handling the case (or raising appropriate errors) when the algorithm has little cash on hand.
When adding or editing docstrings for classes, functions, etc, we use numpy__ as the canonical reference.
__ https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
We have a set of whatsnew <https://github.com/quantopian/zipline/tree/master/docs/source/whatsnew>__ files that are used for documenting changes that have occurred between different versions of Zipline.
Once you've made a change to Zipline, in your Pull Request, please update the most recent whatsnew file with a comment about what you changed. You can find examples in previous whatsnew files.