mirror of
https://github.com/sprockets/sprockets.mixins.mediatype.git
synced 2024-11-25 03:00:24 +00:00
92 lines
3.3 KiB
ReStructuredText
92 lines
3.3 KiB
ReStructuredText
How to Contribute
|
|
=================
|
|
Do you want to contribute fixes or improvements?
|
|
|
|
**AWesome!** *Thank you very much, and let's get started.*
|
|
|
|
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 endeavors::
|
|
|
|
$ python3 -m venv 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`_.
|
|
The next step is to install the development tools that this project uses.
|
|
These are listed in *requires/development.txt*::
|
|
|
|
$ env/bin/pip install -qr requires/development.txt
|
|
|
|
At this point, you will have everything that you need to develop at your
|
|
disposal. Use the unittest runner to run the test suite or the coverage
|
|
utility to run the suite with coverage calculation enabled::
|
|
|
|
$ coverage run -m unittest
|
|
$ coverage report
|
|
|
|
You can also run the tox utility to verify the supported Python versions::
|
|
|
|
$ tox -p auto
|
|
✔ OK py37 in 2.636 seconds
|
|
✔ OK py38 in 2.661 seconds
|
|
✔ OK py39 in 2.705 seconds
|
|
_________________________________________________________________________
|
|
py37: commands succeeded
|
|
py38: commands succeeded
|
|
py39: commands succeeded
|
|
congratulations :)
|
|
|
|
For other commands, *setup.py* is the swiss-army knife in your development
|
|
tool chest. It provides the following commands:
|
|
|
|
**./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
|
|
unittest runner::
|
|
|
|
$ python -m unittest tests
|
|
|
|
That's the quick way to run tests. The slightly longer way is to run
|
|
the `tox`_ 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::
|
|
|
|
$ tox -p auto
|
|
✔ OK py37 in 2.636 seconds
|
|
✔ OK py38 in 2.661 seconds
|
|
✔ OK py39 in 2.705 seconds
|
|
__________________________________________________________________________
|
|
py37: commands succeeded
|
|
py38: commands succeeded
|
|
py39: 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: https://flake8.pycqa.org/
|
|
.. _sphinx: https://sphinx-doc.org/
|
|
.. _tox: https://tox.readthedocs.io/
|