CONTRIBUTING.rst

Contributing

How to develop on this project

Get the code from the repository

The development of zammadoo takes place on GitHub. The main branch should contain the most recent and working code. For a checkout of the the files run

git clone -b main https://github.com/flashdagger/zammadoo.git

If you have a GitHub account you can fork the project from https://github.com/flashdagger/zammadoo and create your own development branch.

Setting up your own virtual environment

The repository includes a pyproject.toml file to help you set up a virtual environment and install the needed development dependencies. You can use UV to setup a virtual environment. From the repository checkout root directory execute:

uv sync

Run the unit tests to ensure everything is working

Run pytest to run the tests. For details see the pytest project.

Create a new branch to work on your contribution

Run git checkout -b my_contribution

Make your changes

Edit the files using your preferred editor. (we recommend VIM or VSCode)

Format the code

Run black zammadoo to format the code.

Run the linter

Run pylint zammadoo to run the linter.

Test your changes

Add unit tests to your PR and run pytest --cov-report html to run the tests. Ensure the code coverage report in report/index.html includes your changes.

Build the documentation locally

# install the optional dependencies for building the documentation
uv pip install -r docs/requirements.txt
# build the HTML documents
docs\make.bat html  # Windows
make -C docs html   # Linux, MacOS

Open the docs/_build/html/index.html in your browser to ensure your new changes are documented.

Commit your changes and push to your fork

Run git push -u origin my_contribution

Submit a pull request

On github interface, click on Pull Request button. Wait CI to run and one of the developers will review your PR.