Developers guide

Contributions and reporting issues

We welcome reporting of issues on our GitHub page. Please provide a minimum working example so we are able to reproduce the issue. Furthermore, we welcome contributions. We follow the ColPrac guide for collaborative practices. New contributors should make sure to read that guide.

To get started with local development, install Julia and prek (a fast, Rust-based Git hooks manager and drop-in replacement for pre-commit) by running the command below.

pixi run install

Test and example data

Wflow test model configurations (.toml files under Wflow/test) are tracked directly in Git. Their input data under Wflow/test/data/input is versioned with DVC: Git tracks the directory through Wflow/test/data/input.dvc, while the files themselves are stored in the public wflow/testdata folder on the Deltares MinIO server. Download the input data matching the current Git revision with:

pixi run download-test-data

Maintainers can update the data using the write-testdata DVC remote. Configure MinIO credentials locally or through the standard AWS environment variables; never commit credentials. After changing files under Wflow/test/data/input, update and publish the DVC state with:

pixi run dvc add Wflow/test/data/input
pixi run dvc push --remote write-testdata

utils/example_models.toml defines which Git-tracked configuration and which DVC-tracked input files together constitute each example model used by the documentation. A DVC pipeline packages these selections into three public archives as non-cached, persistent outputs. On main these are published under wflow/examples/dev; release branches use their corresponding wflow/examples/vX.Y folder. After updating test data, example configurations, the selection, or the publishing utility, publish the archives and commit the updated lockfile:

pixi run dvc repro publish-example-models
git add Wflow/test/data/input.dvc dvc.lock

When creating the minor release branch release/vX.Y (for any X or Y), replace examples/dev with examples/vX.Y in the stage command and all outputs in dvc.yaml. Make the same replacement in the download links in docs/getting_started/download_example_models.qmd, then publish and commit the release-specific pipeline state:

pixi run dvc repro publish-example-models
git add dvc.yaml dvc.lock docs/getting_started/download_example_models.qmd

CI only downloads the DVC data and checks dvc status; it never uploads data. A consistency failure means that a maintainer must reproduce the stage and commit dvc.lock before merging.

Parameter and variable metadata JSON export

Wflow maintains an internal standard name system (STANDARD_NAME_MAPS) that serves as the single source of truth for all parameter and variable metadata — including units, defaults, descriptions, and input handling flags. A utility script exports this metadata to machine-readable JSON files, making it accessible for external tools, documentation generation, and validation.

Output files

The export produces four JSON files in utils/export_parameter_data/:

File Contents
sbm_metadata.json Land hydrology (SBM) parameters and variables
routing_metadata.json Routing parameters and variables
sediment_metadata.json Soil erosion and sediment transport parameters and variables
domain_metadata.json Domain grid parameters (LDD, river mask, subbasins)

JSON structure

Each file is a flat JSON object keyed by CSDMS-style standard names. The output is validated against a JSON Schema (metadata_schema.json in the same directory). Internal-only fields (lens, dimname, tags) from ParameterMetadata are intentionally excluded from the JSON output. The full field descriptions are documented on the struct:

Code 
using Wflow
@doc Wflow.ParameterMetadata

Metadata associated with parameters and variables.

Arguments

  • lens: The path in the model data structure to the parameter/variable if it exists

  • unit: The unit of the parameter/variable in the Wflow input

  • default: The default (initial) value of the parameter/variable if it exists Note: the defaults are NOT in SI units!

  • fill: Missing input values are replaced by this value if allow_missing == false

  • type: The output type of the data. Assumed to be Float64 if it is not provided and cannot be derived from default or fill

  • description: The description of the parameter/variable provided in the Wflow docs

  • allow_missing: Whether the parameter/variable is allowed to have missing entries

  • allow_dynamic_input: Allow updating this parameter from input via cyclic/forcing

  • dimname: The name of the third dimension of the parameter/variable if it exists

  • tags: Identifiers to filter parameters/variables for specific tables in the docs

Running the export

Use the pixi task:

pixi run parameter_metadata_json_gen

CI guardrail

A GitHub Actions workflow (parameter_metadata_json_gen.yml) runs automatically on pushes to main and on PRs that modify files under Wflow/src/standard_name/. It re-generates the JSON files and runs git diff --exit-code to ensure the committed JSON stays in sync with the source standard name maps. If you update any standard name metadata, re-run the export and commit the updated JSON files.

Style/decisions

  • For improved code readability, we decided to avoid non-ASCII characters for naming variables, structs, functions and macros. Using the non-ASCII character for built-in operators is still allowed. This change in naming convention is now in effect and all invalid uses of non-ASCII characters have been replaced by ASCII equivalents.
Back to top