diff options
author | Ashley Camba Garrido <ashwoods@gmail.com> | 2017-08-09 17:10:14 +0200 |
---|---|---|
committer | Ashley Camba Garrido <ashwoods@gmail.com> | 2017-08-09 17:12:00 +0200 |
commit | 0164c26d29daa93628a65eca8e9423666e70dc2c (patch) | |
tree | 90052a424c164571ba4d8c7baa6db3168c30c79f | |
parent | ad3379ac845b9b9c21a425e184daf7ecd517ddf8 (diff) | |
download | raven-0164c26d29daa93628a65eca8e9423666e70dc2c.tar.gz |
Update contributing docs with tox/travis usage
-rw-r--r-- | docs/contributing.rst | 64 |
1 files changed, 46 insertions, 18 deletions
diff --git a/docs/contributing.rst b/docs/contributing.rst index 560142d..e08b112 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -4,39 +4,67 @@ Contributing Want to contribute back to Sentry? This page describes the general development flow, our philosophy, the test suite, and issue tracking. -(Though it actually doesn't describe all of that, yet) +There are many ways to you can help, either by submitting bug reports, improving the +documentation, or submitting a patch. This document describes how to get the +test suite running for the Python SDK. Setting up an Environment ------------------------- -Sentry is designed to run off of setuptools with minimal work. Because of this -setting up a development environment requires only a few steps. +There are several ways of setting up a development environment. If you want to ensure +your changes work across all environments and integrations that Raven supports, +the easiest way to run one or more jobs from test suite matrix is using a virtualenv +management and test command line tool called `Tox`_, -The first thing you're going to want to do, is build a virtualenv and install -any base dependancies. +It is also recommended to have the Python versions you are targeting installed on your +system. There are several tools that help you manage several Python installations, +like `Pyenv`_ or `Pythonz`_, but you can also install them manually by downloading them +from the Python.org website or installing them from repositories depending on your +operating system. -:: +Once you have the Python versions you are going to work with, you have to install `Tox`. +The easiest way of installing `Tox` is by running `pip install tox` into your +default Python installation. - virtualenv ~/.virtualenvs/raven - source ~/.virtualenvs/raven/bin/activate - make +Running the tests +----------------- -That's it :) +Running the tests is easy: just run `tox` from the command line and it will take care of +creating all the necessary virtualenvs and running all the environments defined in the `tox.ini` +file. -Running the Test Suite ----------------------- +During development you might want to run only a certain environment, which can be done by +passing the `-e ENV` to tox, for example: -The test suite is also powered off of py.test, and can be run in a number of ways. Usually though, -you'll just want to use our helper method to make things easy: +.. code-block:: bash -:: + $ tox -e py35-django19 - make test +which would run the Python3.5 environment and the Django integration tests with Django 1.9. +You can list all the defined environments with `tox --listenvs`, or fall into the Python debugger +on any raised exception by using `tox --pdb`. Please refer to the Tox Documentation for additional +information. Contributing Back Code ---------------------- -Ideally all patches should be sent as a pull request on GitHub, and include tests. If you're fixing a bug or making a large change the patch **must** include test coverage. +Ideally all patches should be sent as a pull request on GitHub, and include tests. +If you're fixing a bug or making a large change the patch **must** include test coverage. + +You can see a list of open pull requests (pending changes) by visiting our `Github Pull Request` page. +Every pull requests triggers a test build on our Travis CI where you can verify that +all tests pass. + +Notes +----- + +In order to use Pyenv with Tox, create a `.python-version` file similar to the +`.python-version-example` in the project root. + -You can see a list of open pull requests (pending changes) by visiting https://github.com/getsentry/raven-python/pulls +.. _Sentry: https://getsentry.com +.. _Github Pull Request: https://github.com/getsentry/raven-python/pulls +.. _Tox: https://tox.readthedocs.io +.. _Pythonz: https://github.com/saghul/pythonz +.. _Pyenv: https://github.com/pyenv/pyenv
\ No newline at end of file |