***********************
Contribution Guidelines
***********************

The |project| project uses the `Gitlab Flow`_ :cite:`gitlab` workflow model.

Git Commit Message
==================

Begin Git commit messages with one of the following headings:

* BUG: bug fix
* DOC: documentation
* FEAT: feature
* MAINT: maintenance
* TST: tests
* REL: release
* WIP: work-in-progress

For example:

.. code:: bash

   git commit -m "FEAT: short intent of new feature"
   git commit -m "BUG: fixes nasty bug"
   git commit -m "DOC: adds documentation for feature"

reStructured Text
=================

`Sphinx`_ reads in docstrings and other special portions of the code as
reStructured text. Developers should follow styles in this `Sphinx style
guide`_.

Style Guide
===========

This project uses the `Ruff`_ autoformatting and style guide. The Ruff default options are found in
``pyproject.toml.in``. See the :ref:`build` section for a discussion about the need for templating the configuration
file.

The style guide checks are run with the following alias

.. code-block::

   $ scons style

You can autoformat Python and SConscript files with the following command.

.. code-block::

   $ scons ruff-format

You can also run the style checks and format files with ``ruff`` directly, but bear in mind that the project uses a
template ``pyproject.toml.in`` file, so any changes to the ``ruff`` configuration must be followed by a re-build of the
``pyproject.toml`` file prior to running checks and formatting commands. This dependence is explicitly captured in the
``style`` and ``ruff-format`` aliases, so it is not necessary to explicitly re-build the ``pyproject.toml``
configuration file when using the aliases.

.. code-block::

   $ scons pyproject.toml && ruff check . && ruff format . --check
   $ scons pyproject.toml && ruff check . --fix; ruff format .
