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.
- object == config. Code objects and the YAML config are congruent, close to 1:1; only values derived at instantiation are exempt.
- Mutation is guarded. Every value that changes across timesteps or iterations is a
LockedState(src/tango_core/core/locked_state.py) inside the component'sstatedataclass, written exactly once per solve. - History is recordable. Every
*Statefield has alist[T]twin in the matching*History, appended inrecord(). Exception:EconomicState, which runs once throughfinalize(). - Single source of truth. Data several objects need is shared by reference, never copied.
- Deterministic quality checks. Every change passes mypy strict, Ruff lint and format, and pytest;
just checkruns them locally, and CI runs them again on every pull request. - Docstrings follow the Google style and document arguments, attributes and return values; the API reference is generated from them.
- Schemas defined in code. Config and persisted state are pydantic fields. Exempt: orchestration internals,
LockedStateruntime state, and framework primitives, none of which is loaded from or dumped to config. - No
eval. - Unit conversions are defined in, and imported from,
src/tango_core/core/constants.py. - Enums for finite variants. A parameter with a small, finite set of values is a
StrEnum. - No silent base-class methods. An unimplemented method raises
NotImplementedError, neverpass. - 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'sp_unit='bar'hides the unit and is not used. - No opaque short names for physical quantities:
wellbore_diameter_m, notrw, so a radius cannot be passed where a diameter is expected. - Document private attributes. Every
_namehas a comment. - Encapsulated mutation. Only the instance modifies its fields; external code never assigns
obj.field = value.stateandStreamfields are.update()d throughLockedState. Compliance is not yet audited (docs/tango_tasks.md). - YAML booleans are
True/False, neveryes/no/on/off: PyYAML and YAML 1.2 parsers read those differently. - Every
templates/YAML is regression-tested byjust 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.
- Check that
## [In Development]inCHANGELOG.mdcovers the release, then rename it to## [X.Y.Z] — YYYY-MM-DDand setversionanddate-releasedinCITATION.cff. - Bump
versioninpyproject.tomlonmainthrough a pull request. Itslicense-checkjob (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 uploadslicenses.jsonand a draw.io dependency tree) and either replace the dependency or add aREVIEWED_PACKAGESentry intools/check_licenses.pygiving the reason, through its own pull request. - Install RAFT with
just setup-raft, then tag that commit and push the tag. The pre-push hook runsjust test --allfirst 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
- The tag starts the
releaseworkflow. It checks that the tag matchesversioninpyproject.toml, builds the wheel and sdist once, and uploads them to TestPyPI. - 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
- If it works, approve the waiting
publish to PyPIjob 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. - 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-tagneeds 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 fromCITATION.cff, whosedoiis 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: ownerGEG-ETHZ, repositoryTANGO-core, workflowrelease.yml, environmentpypion PyPI andtestpypion TestPyPI. Before the first upload this is a "pending publisher", which also reserves the name. - In the repository's Settings → Environments, create
testpypiwith no protection rules andpypiwith 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-coreoff 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.