Publishing CityLearn

CityLearn is distributed as citylearn and imports as citylearn. The release maintainer is Tiago Fonseca.

Prepare the release

Update the version in citylearn/__init__.py.
Add a user-facing entry to releases.md, including compatibility, dataset/schema impact, validation scope and migration instructions.
Update the affected guides and migration notes.
Run the tests and auditors in the developer guide, build the Sphinx site and check its links and examples.
Build and validate wheel/source distributions, then verify the installed wheel outside the checkout. The workflow’s installed-export check demonstrates this.

python -m build
python -m twine check dist/*

Keep raw validation output in CI or release artifacts. Document measured improvements with the baseline, inputs, repetitions, metric units and limitations. Move older entries to the release archive without dropping their validation evidence. Keep the latest release and its migration information on the current page.

CI, tagging and publication

Commit the reviewed changes with the maintainer’s identity, push once and wait for the relevant CI to pass. Tag the approved commit as vX.Y.Z.

The publication workflow runs when a GitHub Release is published or when explicitly dispatched. Choose one trigger per release. A tag push by itself does not publish the package.

The build job checks the distributions and installed exports. The publish job uses the existing citylearn PyPI project and the GitHub pypi environment’s configured credentials. Confirm both jobs succeeded for the intended commit and verify the pinned package from PyPI in a clean environment.

Version policy

Type	Use when
Patch	Compatible fixes, documentation or small additive changes.
Minor	A substantial capability or schema/API change.
Major	Broad breaking changes.

Release entries should explain what changes for users, required migration, validation performed and its limits. A local documentation edit does not require publication or imply that a new version already exists.