CONTRIBUTING.rst

########################
Contribution Guidelines
#######################

Flask-Flatpages welcomes any and all contributions. This file
documents the tools and conventions we use, and steps to take when submitting
a Pull-Request.

************
Tools
************

We use ``tox`` as a general-purpose tool for automating style-checking,
testing and building documentation of the project. So in principle,
contributing is as simple as 

``python -m pip install tox``

and opening your editor of choice.

Linting and Style
=================

We use ``flake8`` to ensure code in the project conforms to a common
style. The config can be found in ``setup.cfg``. Broadly, the project
uses `smarkets import style <https://github.com/PyCQA/flake8-import-order/blob/master/tests/test_cases/complete_smarkets.py>`_,
and we prefer breaking lines after a binary opertor.

To check the style of any contributions, simply run ``tox -e lint``.

Code is linted as part of the CI pipeline, which runs on push and on opening a pull request.

Tests
=====

Any contributions to Flask-Flatpages will require corresponding test cases. Tests can be found
in the ``tests`` directory in the project root. We use ``unittest`` classes to define tests,
and ``pytest`` as the test runner.

To run the full test suite, simply run ``tox``, which will test against all supported
Python versions present on your machine.

Documentation and Release Notes
===============================

All modules and functions are documented using Python docstrings, and documentation
is then generated using Sphinx.

The project documentaiton is a single-page using the ``flask`` theme. General descriptions
of the project and its operation are contained in ``docs/index.rst``. The API seciton
of the documentation is generated automatically using `autodoc <https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html>`_.

Similarly, the Changelog is automatically generated using `reno <https://docs.openstack.org/reno/latest/user/index.html>`_. When opening a pull request, please create a new
release note by running::

reno new <your-note-name-here>

And then editing the resulting file in ``releasenotes/notes``.


Documentation can be built locally using ``tox -e docs``. A live copy of the
documentation, based on the master branch, is hosted at
`ReadTheDocs <flask-flatpages.readthedocs.io>`_.

*************
PR Checklist
*************

+ Is the code linted with ``tox -e lint``?

+ Are appropriate tests added? Do they pass with ``tox``?

+ Does the PR need a release note? Include one with ``reno``.


*************
Releasing
*************

Releases are automatically handled using a Github Actions pipeline
defined in ``.github/workflows/release.yml``. To make a relase

1. Update the version in `setup.cfg`. ``reno`` can help to generate the
   next version using::

     reno -q semver-next

2. Commit the changes, and tag the commit e.g.::

   git add setup.cfg && git commit && git tag v$(reno -q semver-next)

3. Push the tag and commit to the master branch