spiff-arena/CONTRIBUTING.rst

107 lines
2.6 KiB
ReStructuredText

Contributor Guide
=================
Thank you for your interest in improving this project.
This project is open-source under the `MIT license`_ and
welcomes contributions in the form of bug reports, feature requests, and pull requests.
Here is a list of important resources for contributors:
- `Source Code`_
- `Documentation`_
- `Issue Tracker`_
- `Code of Conduct`_
.. _MIT license: https://opensource.org/licenses/MIT
.. _Source Code: https://github.com/sartography/spiffworkflow-backend
.. _Documentation: https://spiffworkflow-backend.readthedocs.io/
.. _Issue Tracker: https://github.com/sartography/spiffworkflow-backend/issues
How to report a bug
-------------------
Report bugs on the `Issue Tracker`_.
When filing an issue, make sure to answer these questions:
- Which operating system and Python version are you using?
- Which version of this project are you using?
- What did you do?
- What did you expect to see?
- What did you see instead?
The best way to get your bug fixed is to provide a test case,
and/or steps to reproduce the issue.
How to request a feature
------------------------
Request features on the `Issue Tracker`_.
How to set up your development environment
------------------------------------------
You need Python 3.10+ and the following tools:
- Poetry_
Install the package with development requirements:
.. code:: console
$ poetry install
You can now run an interactive Python session,
or the command-line interface:
.. code:: console
$ poetry run python
$ poetry run spiffworkflow-backend
.. _Poetry: https://python-poetry.org/
How to test the project
-----------------------
Run the full test suite from the root of arena:
.. code:: console
$ ./bin/run_pyl
You can also run a specific ci session.
For example, invoke the unit test suite like this:
.. code:: console
$ ./bin/run_ci_session tests
Unit tests are located in the ``tests`` directory,
and are written using the pytest_ testing framework.
.. _pytest: https://pytest.readthedocs.io/
How to submit changes
---------------------
Open a `pull request`_ to submit changes to this project.
Your pull request needs to meet the following guidelines for acceptance:
- ./bin/run_pyl must pass without errors and warnings.
- Include unit tests if practical.
- If your changes add functionality, update the documentation accordingly.
It is recommended to open an issue before starting work on anything.
This will allow a chance to talk it over with the owners and validate your approach.
.. _pull request: https://github.com/sartography/spiff-arena/pulls
.. github-only
.. _Code of Conduct: CODE_OF_CONDUCT.rst