mirror of
https://github.com/sprockets/sprockets.mixins.mediatype.git
synced 2024-12-27 11:17:30 +00:00
Merge pull request #37 from dave-shawley/contributing-docs
Make contribution guidelines more visible
This commit is contained in:
dave-shawley
GitHub
commit
10825d29fa
2 changed files with 89 additions and 92 deletions
88
CONTRIBUTING
Normal file
88
CONTRIBUTING
Normal file
|
|
@ -0,0 +1,88 @@
|
|||
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 using 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 our CI pipeline
|
||||
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 CI pipeline passes then someone will review it, and eventually merge
|
||||
it back.
|
||||
|
|
@ -1,92 +1 @@
|
|||
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/
|
||||
.. include:: ../CONTRIBUTING
|
||||
|
|
|
|||
Loading…
Reference in a new issue