Contributing

Contributions or forking of the project is always welcome. Below will provide a quick outline of how to get setup and things to be aware of when contributing.

Reporting issues

If you simply want to report an issue, you can use the GitHub Issue page.

Setting up the development environment

This package is built using Pipenv, which will take care of both your virtual environment and package management. If needed, you can install pipenv through pip:

$ pip install pipenv

To download the repository from GitHub via git:

$ git clone git://github.com/studybuffalo/django-helcim.git

You can then install all the required dependencies by changing to the package directory and installing from Pipfile.lock:

$ cd django-helcim
$ pipenv install --ignore-pipfile --dev

Finally, you will need to build the package:

$ pipenv run python setup.py develop

You should now have a working environment that you can use to run tests and setup the sandbox demo.

Testing

All pull requests must have unit tests built and must maintain or increase code coverage. The ultimate goal is to achieve a code coverage of 100%. While this may result in some superfluous tests, it sets a good minimum baseline for test construction.

Testing format

All tests are built with the pytest framework (and pytest-django for Django-specific components). There are no specific requirements on number or scope of tests, but at a bare minimum there should be tests to cover all common use cases. Wherever possible, try to test the smallest component possible.

Running Tests

You can run all tests with the standard pytest command:

$ pipenv run py.test

To check test coverage, you can use the following:

$ pipenv run py.test --cov=helcim --cov-report=html

You may specify the output of the coverage report by changing the --cov-report option to html or xml.

Sandbox

You may find it easier to do testing within the sandbox enviroments. See the Sandbox page for additional details on setting up and configuring the sandbox sites if you haven’t already done so as part of the django-helcim installation.

Updating documentation

All documentation is hosted on Read the Docs and is built using Sphinx. All the module content is automatically built from the docstrings and the sphinx-apidoc tool and the sphinxcontrib-napoleon extension.

Docstring Format

The docstrings of this package follow the Google Python Style Guide wherever possible. This ensures proper formatting of the documentation generated automatically by Sphinx. Additional examples can be found on the Sphinx napoleon extension documentation.

Building package reference documentation

The content for the Package reference is built using the sphinx-apidoc tool. If any files are added or removed from the helcim module you will need to rebuild the helcim.rst file for the changes to populate on Read the Docs. You can do this with the following command:

$ pipenv run sphinx-apidoc -fTM -o docs helcim helcim/migrations helcim/urls.py helcim/apps.py helcim/admin.py

Linting documentation

If you are having issues with the ReStructuredText (reST) formatting, you can use rst-lint to screen for syntax errors. You can run a check on a file with the following:

$ pipenv run rst-lint /path/to/file.rst

Distributing package

Django Helcim is designed to be distributed with PyPI. While most contributors will not need to worry about uploading to PyPI, the following instructions list the general process in case anyone wishes to fork the repository or test out the process.

Note

It is recommended you use TestPyPI to test uploading your distribution while you are learning and seeing how things work. The following examples below will use TestPyPI as the upload target.

To generate source archives and built distributions, you can use the following:

$ pipenv run python setup.py sdist bdist_wheel

To upload the distributions, you can use the following twine commands:

$ pipenv run twine upload --repository-url https://test.pypi.org/legacy/ dist/*

You will need to provide a PyPI username and password before the upload will start.