Contributing

Become a contributor

Many team members joined while working on their Bachelor’s or Master’s thesis. If you are a student, why not contribute to flusstools within an innovative thesis? Have a look at the open Bachelor and Master Thesis topics.

You do not have to be a student to join - just reach out to Sebastian Schwindt.

How the project is organized

flusstools lives in two GitHub repositories:

• flusstools-pckg - the Python code, released to PyPI.

• flusstools-docs - this documentation (the .rst text files).

The documentation installs flusstools straight from PyPI and builds the function/class reference automatically from the docstrings in the code. So you never copy code into the docs repo - you publish a release of the code, and edit the text here.

Set up a development environment

GDAL only installs reliably with conda/mamba (see Installation). Clone the code repo, create the environment, and install flusstools in editable mode:

git clone https://github.com/Ecohydraulics/flusstools-pckg.git
cd flusstools-pckg
mamba env create -f environment.yml
mamba activate flussenv
pip install -e . --no-deps

--no-deps is used because all dependencies already come from environment.yml. “Editable” (-e) means your code changes take effect immediately, without reinstalling.

Write code

A few rules keep the package clean and the docs working:

• Imports: every module imports exactly what it uses, at the top of the file - there is no central import file. To use a function from another flusstools module, import it directly from where it is defined, e.g. from ..geotools.geotools import rasterize.

• Docstrings are the docs. Write a Google-style docstring for every public function and class; it is exactly what shows up in this documentation. The sections you normally need:

  • Args: - describe each parameter

  • Returns: - describe what comes back

  • Raises: - errors it may raise (optional)

  • Example: - a short usage snippet (optional, but appreciated)

• Make a function public: if users should be able to call your new function or class, add its name to the __all__ list in that subpackage’s __init__.py.

• Added a new library? Declare it in three places: pyproject.toml (dependencies), environment.yml, and - using its import name (e.g. skfuzzy, not scikit-fuzzy) - the autodoc_mock_imports list in flusstools-docs/docs/conf.py.

• Keep it readable, and only push code that actually runs.

Release a new version

Once your code works and is merged, publish it to PyPI so that users - and these docs - receive it. The full recipe is in CONTRIBUTING.md; the short version:

1. Bump version in flusstools-pckg/pyproject.toml (e.g. 2.0.1 to 2.0.2).

2. Build and upload (needs a PyPI API token):

   mamba run -n flussenv python -m build
   TWINE_USERNAME=__token__ python -m twine upload dist/*
   

3. Tag the release on GitHub:

   git tag -a v2.0.2 -m "FlussTools 2.0.2"
   git push --tags
   

Update this documentation

Edit (or add) the matching .rst file in flusstools-docs/docs/ and push to main - Read the Docs rebuilds automatically:

git clone https://github.com/Ecohydraulics/flusstools-docs.git
cd flusstools-docs
# edit docs/<module>.rst
git commit -am "docs: describe <something>"
git push

To document a new module, add a .. automodule:: flusstools.<subpackage>.<module> block to the matching .rst file (copy the pattern from geotools.rst) and list the page in the toctree of index.rst.

Important

Only push code that you have run successfully - thank you!