Developer Information

Contributions to this project are highly appreciated! You can either contact the maintainers, create an issue or directly create a pull request for your proposed changes:

  1. Fork the Project

  2. Create your Feature Branch (git checkout -b feature/<descriptive-name>)

  3. Commit your changes (git commit -m 'Added NewFeature')

  4. Push to remote (git push origin feature/<descriptive-name>)

  5. Open a Pull Request to be merged with dev

Contributor information

To contribute to this project, please follow these steps:

Dev env setup

  1. Install miniforge.

  2. Create a new virtual environment using conda: Run conda create -n pystatis python=3.11. You can choose another Python version as long as it is supported by this package, see the pyproject.toml for supported Python versions.

  3. Install uv with pip install uv.

  4. Clone the repository via git.

  5. Change into the project root directory.

  6. Run uv sync to install all dependencies. Run uv sync --group dev to receive all additional developer dependencies.

  7. Install pre-commit: Run uv run pre-commit install. This will activate the pre-commit hooks that will run prior every commit to ensure code quality.

Workflow

  1. Check out the dev branch and make sure it is up to date by running git pull.

  2. Create a new branch by running git checkout -b <new-branch> or git switch -c <new-branch>. If possible, add an issue number to the branch name.

  3. Make your changes.

  4. Delete the cassettes folder under tests to make sure that the tests are loading the latest data from the API.

  5. Run uv run pytest tests -sx -vv --vcr-record=new_episodes to see if all existing tests still run through.

  6. Add new tests depending on your changes.

  7. Run uv run pytest tests -sx -vv --vcr-record=new_episodes again to make sure your tests are also passed.

  8. Commit your changes. This will trigger all pre-commit hooks as defined in .pre-commit-config.yaml. If any of these pre-hooks fails, your commit is declined, and you have to resolve the issues first.

  9. Before you create a PR make sure that you have the latest changes from dev. Run git switch dev, run git pull, switch back to your branch with git switch - and either do a git rebase -i dev or git merge dev to get the latest changes in your current working branch. Solve all merge conflicts.

  10. Push your final changes.

  11. Create a new PR, always against dev as target.

To learn more about uv, see the official uv documentation.

Documentation process

Documentation can also be built locally by ensuring that pandoc is installed, e.g. via uv pip install pandoc, and then running

cd docs && make clean && make html

from the project root directory. Besides providing parsed docstrings of the individual package modules, the full documentation currently mirrors most of the readme, like installation and usage. The mirroring crucially relies on the names of the section headers in the ReadMe, so change them with care!

More information on how to use sphinx is provided here.