Skip to content

Contributing to TANGO

For anyone changing TANGO's code, configs or documentation: the setup, the rules every change follows, and how a change gets from a branch to a release. TANGO is released under the Apache License 2.0 (see LICENSE.txt); contributors are GEG members with write access to GEG-ETHZ/TANGO-core.

Development setup

Python 3.11, uv, just, gitleaks and SSH access to GitHub.

git clone git@github.com:GEG-ETHZ/TANGO-core.git tango-core
cd tango-core
just setup        # uv sync, direnv allow, and the git hooks

The hooks are managed by prek from .pre-commit-config.yaml. On commit: Ruff, whitespace and YAML checks, gitleaks, the src/tango_core.hash refresh. On push: remote freshness, mypy, the fast pytest subset, the release-tag gate. They block commits and pushes to main and develop. Skip a single hook with SKIP=<id>, never with --no-verify. The gitleaks hook sees only what a commit stages; just leaks scans the whole history, every branch and tag.

TANGO Commandments

Binding for every change; each exists because its absence caused a real problem.

  1. object == config. Code objects and the YAML config are congruent, close to 1:1; only values derived at instantiation are exempt.
  2. Mutation is guarded. Every value that changes across timesteps or iterations is a LockedState (src/tango_core/core/locked_state.py) inside the component's state dataclass, written exactly once per solve.
  3. History is recordable. Every *State field has a list[T] twin in the matching *History, appended in record(). Exception: EconomicState, which runs once through finalize().
  4. Single source of truth. Data several objects need is shared by reference, never copied.
  5. Deterministic quality checks. Every change passes mypy strict, Ruff lint and format, and pytest; just check runs them locally, and CI runs them again on every pull request.
  6. Docstrings follow the Google style and document arguments, attributes and return values; the API reference is generated from them.
  7. Schemas defined in code. Config and persisted state are pydantic fields. Exempt: orchestration internals, LockedState runtime state, and framework primitives, none of which is loaded from or dumped to config.
  8. No eval.
  9. Unit conversions are defined in, and imported from, src/tango_core/core/constants.py.
  10. Enums for finite variants. A parameter with a small, finite set of values is a StrEnum.
  11. No silent base-class methods. An unimplemented method raises NotImplementedError, never pass.
  12. Unit suffixes. A non-SI value names its unit (p_out_megapascals) and is converted where it is read; SI values carry no suffix. A file-global unit such as TESPy's p_unit='bar' hides the unit and is not used.
  13. No opaque short names for physical quantities: wellbore_diameter_m, not rw, so a radius cannot be passed where a diameter is expected.
  14. Document private attributes. Every _name has a comment.
  15. Encapsulated mutation. Only the instance modifies its fields; external code never assigns obj.field = value. state and Stream fields are .update()d through LockedState. Compliance is not yet audited (docs/tango_tasks.md).
  16. YAML booleans are True/False, never yes/no/on/off: PyYAML and YAML 1.2 parsers read those differently.
  17. Every templates/ YAML is regression-tested by just test --all, against a golden value or for structural sanity; a smoke run alone does not count. A golden value is set or changed only from a run whose results someone has checked, and the commit says how.

How a change moves

Branch Purpose From Into
main Release-ready; tags are cut here — —
develop Integration main main, by pull request, as a merge commit
dev/<feature>, fix/<issue> One change develop or main develop, as a squash merge; main only with the lead developer's sign-off
exp/<name> Experiments anywhere usually abandoned

Every merge into main or develop is a pull request with one approval and green CI (format, lint, mypy, generated-docs check, tests/unit/, and docs build), on a branch that is up to date with its target. Changes users will notice get a changelog entry. Branch protection and merge strategies are repository settings, set once by an admin.

Commits follow Conventional Commits, without emoji, fix(orchestrators): reset Aitken state between timesteps; the types and rules are in .agent/rules/commit-permissions.md.

Testing

Command Runs When
just check Format, lint, type check, fast tests, in CI order Before every push
just test tests/unit/ and the fast part of tests/regtest/ The pre-push hook
just test --all Everything, over an hour Before a release tag, and before merging numerics changes
just test --templates Every templates/*.yml against its golden LCOE When a config or a model changes
just apps A smoke run of every script in applications/ When an application changes

CI runs tests/unit/ only; the regression tier exceeds the runner's time limit. A new feature or fix comes with a test that fails without it.

Documentation

just docs previews the site, just docs-build is what CI runs. The internal pages (task log, roadmap, archive, design notes, Euler guide) are not on the public site; just docs-internal --open builds the site with them and opens it in a browser. A behavior change updates the page that describes it in the same pull request (docs/architecture/, docs/runtime/, the subpackage README.md). The API reference comes from docstrings; diagram rules and the palette are in docs/AGENTS.md; just diagrams regenerates the diagrams from tools/diagrams/.

Large Files

Store meshes and other large binary inputs with DVC, not git: dvc add <file>, commit the .dvc file, and run dvc push. The check-added-large-files hook rejects files over 500 KB.

The one exception is templates/raft/AGS_single.msh (1.1 MB), the mesh of the RAFT example. It's committed to git, and excluded from check-added-large-files, so CI can run RAFT without DVC credentials.

License headers

TANGO is licensed under Apache-2.0 and follows the REUSE specification. Every Python file starts with:

# SPDX-FileCopyrightText: 2025 ETH Zurich
# SPDX-License-Identifier: Apache-2.0

A shebang line, if any, stays above them. Other files are covered by the file-type patterns in REUSE.toml, which deliberately leave out *.py, so a Python file without the header fails the check. A file of a new type fails it too: add its pattern to REUSE.toml. A file from a third party keeps its own copyright and license: give it an annotation in REUSE.toml, and add its license text to LICENSES/. The reuse prek hook runs reuse lint on every commit.

Changelog

CHANGELOG.md follows Keep a Changelog. Entries collect under ## [In Development] until a release is cut, then move under ## [X.Y.Z] — YYYY-MM-DD, and the comparison links in the footer are updated. Since 1.0, an entry is required per release and optional per merge.

Cutting a Release

Choosing the version

Versions follow Effort-based Versioning (EffVer), MACRO.MESO.MICRO. The number tells users how much work upgrading takes, not whether anything changed in an incompatible way. Judge the release by its effort for a typical user:

Bump When upgrading takes Examples
Macro (2.0.0) Real effort: users must change configs, scripts, or code Renaming the package or a config key, removing an injection mode
Meso (1.2.0) Little effort, or none for most users A new component or optional key, a break in a feature few people use
Micro (1.1.1) No effort Bug fixes, documentation, performance

Whatever the bump, every change a user may have to make goes in the release's Breaking section of CHANGELOG.md.

Steps

Every release goes to TestPyPI first and to PyPI only after the TestPyPI upload installs and runs. PyPI never accepts the same version twice, so a broken upload there can't be replaced. Tags carry a v prefix. .github/workflows/release.yml does the uploads with PyPI Trusted Publishing, so no API token is stored anywhere.

  1. Check that ## [In Development] in CHANGELOG.md covers the release, then rename it to ## [X.Y.Z] — YYYY-MM-DD and set version and date-released in CITATION.cff.
  2. Bump version in pyproject.toml on main through a pull request. Its license-check job (tools/check_licenses.py) fails if a runtime dependency's license is not allowed; do not tag until it passes. Review each flagged license (the job uploads licenses.json and a draw.io dependency tree) and either replace the dependency or add a REVIEWED_PACKAGES entry in tools/check_licenses.py giving the reason, through its own pull request.
  3. Install RAFT with just setup-raft, then tag that commit and push the tag. The pre-push hook runs just test --all first and blocks a failing tag; it refuses to run without RAFT, whose tests would otherwise skip themselves. Never reuse a version number.
git checkout main && git pull
git tag vX.Y.Z
git push origin refs/tags/vX.Y.Z
  1. The tag starts the release workflow. It checks that the tag matches version in pyproject.toml, builds the wheel and sdist once, and uploads them to TestPyPI.
  2. Install the TestPyPI upload in a fresh directory and check it runs. The extra index supplies the dependencies, which are not on TestPyPI:
uv venv && uv pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ --index-strategy unsafe-best-match tango-core==X.Y.Z
uv run tango_core --version
uv run tango_core init demo && uv run tango_core run demo/templates/hydro_sf_electric.yml --no-save
  1. If it works, approve the waiting publish to PyPI job in the workflow run (Actions → release). The same files go to PyPI. If it doesn't, leave the job unapproved, fix the problem, and release the next patch version; that version number is spent on TestPyPI.
  2. Create a GitHub Release from the tag with the changelog section as its notes (gh release create vX.Y.Z --verify-tag --title X.Y.Z --notes-file notes.md; --notes-from-tag needs an annotated tag). Publishing the release makes Zenodo archive it and mint a DOI for the version; a draft or a bare tag doesn't. Zenodo reads the authors, license, and abstract from CITATION.cff, whose doi is the all-versions DOI and stays the same.

One-time setup

  • On pypi.org and test.pypi.org, add a trusted publisher for project tango-core: owner GEG-ETHZ, repository TANGO-core, workflow release.yml, environment pypi on PyPI and testpypi on TestPyPI. Before the first upload this is a "pending publisher", which also reserves the name.
  • In the repository's Settings → Environments, create testpypi with no protection rules and pypi with a required reviewer.
  • On Zenodo, log in, click "Sync now", and turn on GEG-ETHZ/TANGO-core. Zenodo lists public repositories only, and it ignores releases published before the switch was on.

Handing over Zenodo

Two kinds of Zenodo access matter, and they differ in how many people can hold them:

  • Editing the record: any number of people can have "Can manage" on the TANGO record (record page → Share → People). Keep several maintainers on it, so a departure never leaves the record without an editor.
  • Archiving new releases: the GitHub integration runs through the one Zenodo account that turned the repository on. If that person leaves GEG-ETHZ, new releases may stop reaching Zenodo, so hand it over while they still have access:
  • Make sure the successor has "Can manage" on the record.
  • The current owner turns GEG-ETHZ/TANGO-core off in Zenodo's Settings → GitHub, and the successor turns it on from their own account.
  • Publish the next GitHub Release and check that the new version appears under the all-versions DOI in CITATION.cff, not as a new record with a new all-versions DOI.