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.
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
$ pip install pipenv
To download the repository from GitHub via
$ git clone git://github.com/studybuffalo/django-flexible-subscriptions.git
You can then install all the required dependencies by changing to the
package directory and installing from
$ cd django-flexible-subscriptions $ 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.
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.
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.
You can run all tests with the standard
$ pipenv run py.test
To check test coverage, you can use the following:
$ pipenv run py.test --cov=subscriptions --cov-report=html
You may specify the output of the coverage report by changing the
--cov-report option to
You may run the linters within your IDE/editor or with the following commands:
$ pipenv run pylint subscriptions/ sandbox/ $ pipenv run pylint tests/ --min-similarity-lines=12 $ pipenv run pycodestyle --show-source subscriptions/ sandbox/ tests/
Of note, tests have relaxed rules for duplicate code warnings. This is to minimize the level of abstraction that occurs within the tests with the intent to improve readability.
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.
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
subscriptions module you will need to rebuild the
subscriptions.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 subscriptions subscriptions/migrations subscriptions/urls.py subscriptions/apps.py subscriptions/admin.py
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
Django Flexible Subscriptions 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.
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
$ 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.