mirror of
https://github.com/sprockets/sprockets.clients.cassandra.git
synced 2024-12-01 11:19:54 +00:00
122 lines
5.3 KiB
ReStructuredText
122 lines
5.3 KiB
ReStructuredText
|
How to Contribute
|
||
|
|
=================
|
||
|
|
Do you want to contribute fixes or improvements?
|
||
|
|
|
||
|
|
**AWesome!** *Thank you very much, and let's get started.*
|
||
|
|
|
||
|
|
This project is released under the permissive BSD license so you don't have
|
||
|
|
to push changes back unless you want to. Since you are reading this, you
|
||
|
|
have probably made the right decision.
|
||
|
|
|
||
|
|
Set up a development environment
|
||
|
|
--------------------------------
|
||
|
|
The first thing that you need is a development environment so that you can
|
||
|
|
run the test suite, update the documentation, and everything else that is
|
||
|
|
involved in contributing. The easiest way to do that is to create a virtual
|
||
|
|
environment for your endevours::
|
||
|
|
|
||
|
|
$ pyvenv env
|
||
|
|
|
||
|
|
Don't worry about writing code against previous versions of Python unless
|
||
|
|
you you don't have a choice. That is why we run our tests through `tox`_.
|
||
|
|
If you don't have a choice, then install `virtualenv`_ to create the
|
||
|
|
environment instead. The next step is to install the development tools
|
||
|
|
that this project uses. These are listed in *dev-requirements.txt*::
|
||
|
|
|
||
|
|
$ env/bin/pip install -qr dev-requirements.txt
|
||
|
|
|
||
|
|
At this point, you will have everything that you need to develop at your
|
||
|
|
disposal. *setup.py* is the swiss-army knife in your development tool
|
||
|
|
chest. It provides the following commands:
|
||
|
|
|
||
|
|
**./setup.py nosetests**
|
||
|
|
Run the test suite using `nose`_ and generate a nice coverage report.
|
||
|
|
|
||
|
|
**./setup.py build_sphinx**
|
||
|
|
Generate the documentation using `sphinx`_.
|
||
|
|
|
||
|
|
**./setup.py flake8**
|
||
|
|
Run `flake8`_ over the code and report style violations.
|
||
|
|
|
||
|
|
If any of the preceding commands give you problems, then you will have to
|
||
|
|
fix them **before** your pull request will be accepted.
|
||
|
|
|
||
|
|
Running Tests
|
||
|
|
-------------
|
||
|
|
The easiest (and quickest) way to run the test suite is to use the
|
||
|
|
*nosetests* command. It will run the test suite against the currently
|
||
|
|
installed python version and report not only the test result but the
|
||
|
|
test coverage as well::
|
||
|
|
|
||
|
|
$ ./setup.py nosetests
|
||
|
|
|
||
|
|
running nosetests
|
||
|
|
running egg_info
|
||
|
|
writing dependency_links to sprockets.clients.cassandra.egg-info/dependency_links.txt
|
||
|
|
writing top-level names to sprockets.clients.cassandra.egg-info/top_level.txt
|
||
|
|
writing sprockets.clients.cassandra.egg-info/PKG-INFO
|
||
|
|
reading manifest file 'sprockets.clients.cassandra.egg-info/SOURCES.txt'
|
||
|
|
reading manifest template 'MANIFEST.in'
|
||
|
|
warning: no previously-included files matching '__pycache__'...
|
||
|
|
warning: no previously-included files matching '*.swp' found ...
|
||
|
|
writing manifest file 'sprockets.clients.cassandra.egg-info/SOURCES.txt'
|
||
|
|
...
|
||
|
|
|
||
|
|
Name Stmts Miss Branch BrMiss Cover Missing
|
||
|
|
----------------------------------------------------------------------
|
||
|
|
...
|
||
|
|
----------------------------------------------------------------------
|
||
|
|
TOTAL 95 2 59 2 97%
|
||
|
|
----------------------------------------------------------------------
|
||
|
|
Ran 44 tests in 0.054s
|
||
|
|
|
||
|
|
OK
|
||
|
|
|
||
|
|
That's the quick way to run tests. The slightly longer way is to run
|
||
|
|
the `detox`_ utility. It will run the test suite against all of the
|
||
|
|
supported python versions in parallel. This is essentially what Travis-CI
|
||
|
|
will do when you issue a pull request anyway::
|
||
|
|
|
||
|
|
$ env/bin/detox
|
||
|
|
py27 recreate: /.../sprockets.clients.cassandra/build/tox/py27
|
||
|
|
GLOB sdist-make: /.../sprockets.clients.cassandra/setup.py
|
||
|
|
py33 recreate: /.../sprockets.clients.cassandra/build/tox/py33
|
||
|
|
py34 recreate: /.../sprockets.clients.cassandra/build/tox/py34
|
||
|
|
py27 installdeps: -rtest-requirements.txt, mock
|
||
|
|
py33 installdeps: -rtest-requirements.txt
|
||
|
|
py34 installdeps: -rtest-requirements.txt
|
||
|
|
py27 inst: /.../sprockets.clients.cassandra/build/tox/dist/sprockets.clients.cassandra-0.0.0.zip
|
||
|
|
py27 runtests: PYTHONHASHSEED='2156646470'
|
||
|
|
py27 runtests: commands[0] | /../sprockets.clients.cassandra/build/tox/py27/bin/nosetests
|
||
|
|
py33 inst: /../sprockets.clients.cassandra/.build/tox/dist/sprockets.clients.cassandra-0.0.0.zip
|
||
|
|
py34 inst: /../sprockets.clients.cassandra/.build/tox/dist/sprockets.clients.cassandra-0.0.0.zip
|
||
|
|
py33 runtests: PYTHONHASHSEED='2156646470'
|
||
|
|
py33 runtests: commands[0] | /.../sprockets.clients.cassandra/build/tox/py33/bin/nosetests
|
||
|
|
py34 runtests: PYTHONHASHSEED='2156646470'
|
||
|
|
py34 runtests: commands[0] | /.../sprockets.clients.cassandra/build/tox/py34/bin/nosetests
|
||
|
|
_________________________________ summary _________________________________
|
||
|
|
py27: commands succeeded
|
||
|
|
py33: commands succeeded
|
||
|
|
py34: commands succeeded
|
||
|
|
congratulations :)
|
||
|
|
|
||
|
|
This is what you want to see. Now you can make your modifications and keep
|
||
|
|
the tests passing.
|
||
|
|
|
||
|
|
Submitting a Pull Request
|
||
|
|
-------------------------
|
||
|
|
Once you have made your modifications, gotten all of the tests to pass,
|
||
|
|
and added any necessary documentation, it is time to contribute back for
|
||
|
|
posterity. You've probably already cloned this repository and created a
|
||
|
|
new branch. If you haven't, then checkout what you have as a branch and
|
||
|
|
roll back *master* to where you found it. Then push your repository up
|
||
|
|
to github and issue a pull request. Describe your changes in the request,
|
||
|
|
if Travis isn't too annoyed someone will review it, and eventually merge
|
||
|
|
it back.
|
||
|
|
|
||
|
|
.. _flake8: http://flake8.readthedocs.org/
|
||
|
|
.. _nose: http://nose.readthedocs.org/
|
||
|
|
.. _sphinx: http://sphinx-doc.org/
|
||
|
|
.. _tox: http://testrun.org/tox/
|
||
|
|
.. _virtualenv: http://virtualenv.pypa.io/
|