88 lines
2.7 KiB
ReStructuredText
88 lines
2.7 KiB
ReStructuredText
Contributing
|
|
============
|
|
|
|
Contributions to the project are greatly appreciated.
|
|
|
|
Bugs and suggestions
|
|
--------------------
|
|
|
|
You may `submit an issue`_ to GitLab to warn of any bugs, ask for new features,
|
|
or ask any questions that are not answered in this documentation.
|
|
|
|
When reporting a bug, do not forget to put in your version of Python and your
|
|
version of *pyurbantz*. This will greatly help when troubleshooting, as most
|
|
errors often come from version incompatibilities.
|
|
|
|
Development
|
|
-----------
|
|
|
|
Setup
|
|
^^^^^
|
|
|
|
You will need a virtual envionment to work properly. `virtualenvwrapper`_ is
|
|
recommended::
|
|
|
|
git clone https://gitlab.com/Lucidiot/pyurbantz
|
|
cd pyurbantz
|
|
mkvirtualenv -a . pyurbantz
|
|
pip install -e .[dev]
|
|
|
|
This will clone the repository, create a virtual environment named
|
|
``pyurbantz``, then tell pip to let the package be editable (``-e``).
|
|
The ``[dev]`` suffix adds the extra requirements useful for development.
|
|
|
|
Unit tests
|
|
^^^^^^^^^^
|
|
|
|
Unit tests use the standard ``unittest`` package; you may run them using the
|
|
standard ``setup.py`` command::
|
|
|
|
./setup.py test
|
|
|
|
Tests coverage
|
|
^^^^^^^^^^^^^^
|
|
|
|
I aim for 100% coverage on all of my Python packages whenever I add unit
|
|
tests to them; this package is no exception. CI checks use the `coverage`_
|
|
Python package and `codecov`_ to check for test coverage. To get test coverage
|
|
data locally, run::
|
|
|
|
coverage run setup.py test
|
|
|
|
You may then get a short coverage summary in your terminal::
|
|
|
|
coverage report
|
|
|
|
Or generate an HTML report in a ``htmlcov`` folder, which can be browsed
|
|
offline using your favorite web browser and shows line by line coverage::
|
|
|
|
coverage html
|
|
|
|
If you are having issues reaching 100% coverage, try to still add some tests,
|
|
and mention your issues when creating a pull request to the
|
|
`GitLab repository`_.
|
|
|
|
Linting
|
|
^^^^^^^
|
|
|
|
The source code follows the PEP 8 code style and performs CI checks using the
|
|
``flake8`` tool. To perform the same checks locally, run ``flake8`` on the root
|
|
directory of this repository.
|
|
|
|
Documentation
|
|
-------------
|
|
|
|
The documentation you are reading is generated by the `Sphinx`_ tool.
|
|
The text files that hold the documentation's contents are written in
|
|
`reStructuredText`_ and are available under the ``/docs`` folder of the
|
|
`GitLab repository`_.
|
|
They are also subject to linting using the ``doc8`` tool.
|
|
|
|
.. _submit an issue: https://gitlab.com/Lucidiot/pyurbantz/issues/new
|
|
.. _virtualenvwrapper: https://virtualenvwrapper.readthedocs.io
|
|
.. _coverage: https://coverage.readthedocs.io/
|
|
.. _codecov: https://codecov.io/gl/Lucidiot/pyurbantz
|
|
.. _GitLab repository: https://gitlab.com/Lucidiot/pyurbantz
|
|
.. _Sphinx: http://www.sphinx-doc.org/
|
|
.. _reStructuredText: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
|