CONTRIBUTING.md

Contributing to Itchcraft

Setting up Itchcraft for development

To set up Itchcraft, you need three things:

1. The Python version manager pyenv.

2. A system-wide Python installation.

3. The Python dependency manager poetry.

Installing pyenv on Linux

The Python version manager pyenv makes sure you can always keep the exact Python version required by Itchcraft, regardless of your system Python.

To install pyenv on Linux or WSL2, first make sure Python 3 is installed. Then follow the Basic GitHub Checkout method described at github.com/pyenv/pyenv.

Checking your system-wide pyenv installation

To verify your pyenv is working, run:

pyenv --version

Checking your system-wide Python installation

Make sure you have Python 3.8 or higher installed on your system and available in your PATH.

To check, run:

python --version

If that fails, try:

python3 --version

Proceed after you’ve confirmed one of those to work.

Installing Poetry

You’ll need poetry to manage development dependencies and the venv.

If you’re on Linux or WSL2, use your system package manager to install Poetry.

Alternatively, use one of the installation methods described in Poetry’s documentation.

Checking your Poetry installation

To verify Poetry is working, run:

poetry --version

Setting up your virtual environment

To set up your virtual environment, follow these steps:

1. Go to the project root directory.

2. Run pyenv install -s.

3. Run pyenv exec python -m venv .venv.

4. Run poetry install.

You need to do the above steps only once.

To update your dependencies after a git pull, run poetry update.

Development scripts and tasks

To see a list of available tasks, run: poetry run poe tasks

Running Itchcraft

To execute Itchcraft, run:

poetry run poe cli

Running the tests

To execute the tests, run:

poetry run poe tests

To execute a single test, run e. g.:

poetry run poe tests -vv tests/test_api.py::test_hello

Running the linter

To execute the linter, run:

poetry run poe linter

Running the static type check

To execute the static type check, run:

poetry run poe typecheck

Running the entire CI pipeline locally

If you have act installed and a Docker daemon active, run:

act

Generating project documentation

To generate project documentation (HTML and man page), run:

poetry run poe doc

To open the generated HTML documentation in your browser, run:

poetry run poe html

To open the generated manual page in your terminal, run:

poetry run poe man

Maintenance

Refreshing dependencies

If you get errors after a Git pull, refresh your dependencies:

poetry update

Rebuilding the virtual environment

If you’ve run poetry update and you still get errors, rebuild the virtual environment:

poetry install

Checking Itchcraft’s dependencies for compatible updates

To check Itchcraft’s dependencies for compatible updates, run:

poetry update --dry-run

Updating requirements file for Read the Docs

To update the doc/requirements.txt file for Read the Docs, run:

poetry export --only doc --output doc/requirements.txt