Contributing¶
We welcome contributions! Please open issues and pull requests.
Follow PEP8 and the configured Ruff rules.
Add or update tests when changing behavior.
Keep public APIs documented.
Small PRs are easier to review.
Dev setup¶
Use conda-forge for the environment and create it directly from dev-spec.txt:
conda create -n ismip7_dev -c conda-forge --file dev-spec.txt
conda activate ismip7_dev
pip install --no-deps --no-build-isolation -e .
pre-commit install
If you don’t already have a conda base installation set up, we recommend starting with Miniforge.
Build docs locally when editing documentation:
sphinx-build -b html docs docs/_build/html
Add test scripts to scripts/ that can be used to smoke test features.
Building and testing the Fortran extrapolation tools locally¶
The project now includes two small Fortran executables that perform
horizontal and vertical extrapolation used by the i7aof.extrap
package. There is currently no Python fallback; without these
executables the extrapolation workflow cannot be exercised. Until a
conda-forge package including them is published, you need to build and
install them locally for any extrapolation development or testing.
1. Ensure rattler-build base dependencies¶
Install (once) into your base conda environment so you can perform local package builds:
conda install -n base -c conda-forge rattler-build
2. Build a local package¶
From the repository root:
# you could also build in any temp directory outside of the source repo
LOCAL_CHANNEL=${CONDA_PREFIX}/conda-bld
# pick the right variant file for the python version you want to use, e.g.:
VARIANT=conda/variants/linux_64_python3.13.____cp313.yaml
# Build the conda package (this reads conda/recipe.yaml)
rattler-build build -m "$VARIANT" --output-dir "$LOCAL_CHANNEL" -r conda/recipe.yaml
This creates a local channel containing a build of
ismip7-antarctic-ocean-forcing with the compiled Fortran executables:
i7aof_extrap_horizontali7aof_extrap_vertical
3. Create (or recreate) the dev environment including local build¶
You can now create your development environment pulling everything from conda-forge except this package which will come from your local channel. Include the channel before conda-forge so it has priority.
conda create -y -n ismip7_dev -c "$LOCAL_CHANNEL" -c conda-forge --file dev-spec.txt ismip7-antarctic-ocean-forcing
conda activate ismip7_dev
Then install the repo in editable mode (this keeps Python code live while preserving the compiled executables placed by the package):
pip install --no-deps --no-build-isolation -e .
To activate the code linting and formatting tools (required), run:
pre-commit install
4. Verify executable availability¶
which i7aof_extrap_horizontal
which i7aof_extrap_vertical
python -c "import i7aof.extrap as ex; print(ex.load_template_text()[:120])"
If the which commands return paths inside the active environment and
the Python import succeeds, the setup is correct.
5. Rebuilding after changes¶
If you modify the Fortran sources under fortran/, rebuild and then
recreate the environment with the new local build:
# make sure you're back in the base environment
conda deactivate
conda deactivate
conda activate base
LOCAL_CHANNEL=${CONDA_PREFIX}/conda-bld
# delete any packages you already built
rm -rf ${LOCAL_CHANNEL}/*/ismip7-antarctic-ocean-forcing*.conda
# pick the right variant file for the python version you want to use, e.g.:
VARIANT=conda/variants/linux_64_python3.13.____cp313.yaml
# build the package
rattler-build build -m "$VARIANT" --output-dir "$LOCAL_CHANNEL" -r conda/recipe.yaml
# recreate the environment
conda create -y -n ismip7_dev -c "$LOCAL_CHANNEL" -c conda-forge --file dev-spec.txt ismip7-antarctic-ocean-forcing
# activate the environment
conda activate ismip7_dev
# install the python package in editable mode
pip install --no-deps --no-build-isolation -e .
Notes / troubleshooting¶
Clean previous build artifacts by removing
build/subdirectories thatrattler-buildcreates under its cache (see its terminal output for paths) if you suspect a stale build.