CONTRIBUTING.rst
Contributing to django-simple-history
=====================================
.. image:: https://jazzband.co/static/img/jazzband.svg
:target: https://jazzband.co/
:alt: Jazzband
This is a `Jazzband <https://jazzband.co>`_ project. By contributing you agree to abide by the `Contributor Code of Conduct <https://jazzband.co/about/conduct>`_ and follow the `guidelines <https://jazzband.co/about/guidelines>`_.
Pull Requests
-------------
Feel free to open pull requests before you've finished your code or tests.
Opening your pull request soon will allow others to comment on it sooner.
A checklist of things to remember when making a feature:
- Write tests if applicable
- Note important changes in the `CHANGES`_ file
- Update the `README`_ file if needed
- Update the documentation if needed
- Add yourself to the `AUTHORS`_ file
.. _AUTHORS: AUTHORS.rst
.. _CHANGES: CHANGES.rst
.. _README: README.rst
Requirements
------------
The Makefile can be used for generating documentation and running tests.
To install the requirements necessary for generating the documentation and
running tests::
make init
This will install:
- `tox`_: used for running the tests against all supported versions of Django
and Python as well as running tasks like lint, format, docs
- `coverage`_: used for analyzing test coverage for tests
If not using a virtualenv, the command should be prepended with ``sudo``.
.. _tox: http://testrun.org/tox/latest//
.. _coverage: http://nedbatchelder.com/code/coverage/
Documentation
-------------
To regenerate the documentation run::
make docs
Testing
-------
Please add tests for your pull requests and make sure your changes don't break
existing tests.
To run tox and generate an HTML code coverage report (available in the
``htmlcov`` directory)::
make test
To quickly run the tests against a single version of Python and Django (note: you must
``pip install django`` beforehand)::
python runtests.py
Code Formatting
---------------
We make use of `black`_ for code formatting.
.. _black: https://black.readthedocs.io/en/stable/installation_and_usage.html
You can install and run it along with other linters through pre-commit::
pre-commit install
pre-commit run
Once you install pre-commit it will sanity check any commit you make.
Additionally, the CI process runs this check as well.
Translations
------------
In order to add translations, refer to Django's `translation docs`_ and follow these
steps:
1. Ensure that Django is installed
2. Invoke ``django-admin makemessages -l <LOCALE NAME>`` in the repository's root
directory.
3. Add translations to the created
``simple_history/locale/<LOCALE NAME>/LC_MESSAGES/django.po`` file.
4. Compile these with ``django-admin compilemessages``.
5. Commit and publish your translations as described above.
.. _translation docs: https://docs.djangoproject.com/en/dev/topics/i18n/translation/#localization-how-to-create-language-files