Contribution Guide#

Every contribution is welcome!

Report bugs or request features via GitHub Issues.
Documentation (suggestions and improvement on examples and user guides).
Submit code changes (new functionality, refactors, performance fixes, tests).
Help triage issues by confirming bugs or proposing minimal reproductions.

Getting started#

Fork the repository on GitHub and clone your fork:

git clone < link to your fork of repository >

Create a branch for your work:

git checkout -b "feature_short-description"

If you have already created an Issue like for bugs or feature request, you best name your branch starting with #ISSUE_NUMBER (e.g. #3_adapt_docu) Then you could close the Issue with git commit -m “fix #ISSUE_NUMBER” or “close #ISSUE_NUMBER”

Keep your fork in sync with dev to reduce merge conflicts.

Development environment#

Python 3.10 or newer is required.
Create and activate a virtual environment (python -m venv .venv or your preferred tool).
Install weitsicht in editable mode with developer extras:
```
pip install -e .[develop]
```
This pulls in pre-commit, ruff, pyright, pytest, coverage and the doc tooling defined in pyproject.toml.

Alternatively do not install weitsicht but just the needed packages. Since pip does not support installing dependencies without building and installing the package, we need to install all dependencies separately.

# Packages needed for weitsicht to run
pip install numpy, pyproj, shapely, rasterio, rtree, trimesh, tomli

# Test, coverage
pip install pytest, coverage,
# Format, Linting, Type checking
pip install pre-commit, pyright,ruff
# Docu
pip install  pydata_sphinx_theme, sphinx-design

For all the checking and testing there are config files in place. So you should run the tasks without any arguments.

Testing#

All tests must pass otherwise commits and pull requests will not be considered. If you need help on failing tests I am happy to assist. Also within the foler examples all scirpts are tested. Therefore for running test example folder is needed and data from within.

Run the test suite locally before opening a PR:
```
pytest
```
The default options from pyproject.toml include --doctest-modules and enable the slow marker for long-running tests. To skip slow tests:
```
pytest -m "not slow"
```

Quality and consistency#

To ensure that code style and quality is at some standard, it’s mandatory to run checks via ruff and pyright for commits and pull requests.

Formatting (ruff):
```
ruff format
```

Linting (ruff):

ruff check
# Some errors can be fixed automatically like unused imports or sorting of imports
ruff check --fix

Static typing (pyright). pyright is currently configured with typeCheckingMode = "standard":
```
pyright
```

Pre-commit#

Pre-commit.ci is used to check all commits. You can check commits locally by using pre-commit. To run pre-commits locally, install pre-commit once per clone and let them run before each commit. pre-commit is configured to use the current local python installation or activated environment. Otherwise there could be dependency issues for pyright.

pre-commit install

Then it will run on each commit. It will also perform ruff. So if you run all the checking beforehand it should pass without problems. You can check that via:

pre-commit run --all-files

Coverage#

Coverage is configured in pyproject.toml to run pytest. Typical workflow:

coverage run
coverage html  # optional, view in htmlcov/index.html

Documentation#

Docs live in docs/source and use Sphinx. To build locally:

pip install -e .[docs] # if not already installed all developing dependencies
cd docs
make html

Open docs/build/html/index.html in a browser to preview the site.

Pull requests#

Keep changes focused and include a brief summary of what/why.
Add or update tests and docs alongside code changes.

Ensure the checklist below passes before opening a PR:

pytest (plus coverage if relevant)
ruff format
ruff check
pyright
Docs build cleanly when documentation is touched.
pre-commit run --all-files

Every pull request will be checked automatically using pre-commit.ci and running tests workflow.

Support#

If you are unsure how to start or need feedback, open a GitHub Issue with the label question or help wanted and describe your idea or blocker. We are happy to help.