Releases
Releases are driven from the repository root and use the VERSION file as the canonical version source.
Audience: Developer
Context: Use this page when preparing a release or tracing how version information propagates through packages and images.
Core Explanation
VERSION is the single source of truth for the open-source version.
That value is consumed by:
- Python package metadata in
pyproject.toml - runtime version exports such as
caracal/_version.py - release scripts under
scripts/ - docs version surfaces such as
docs/VERSION
Release Surfaces
| Surface | File or tool |
|---|---|
| package version | VERSION, pyproject.toml, setup.py |
| runtime code version | caracal/_version.py |
| docs version | docs/VERSION |
| release automation | scripts/update-version.sh, scripts/release.sh |
| image build automation | scripts/build-images.sh |
Practical Usage
Minimal version update:
echo "1.0.0" > VERSION
./scripts/update-version.sh
Interactive release flow:
./scripts/release.sh
Internal Behavior
The current release scripts are intentionally lightweight:
update-version.shconfirms the canonical version and updates references where neededrelease.shreadsVERSION, runs the update step, and can optionally create a git tag, build images, and publish artifacts
The release tooling is repository-driven rather than a separate release service.
Edge Cases And Constraints
- Enterprise deployment assets are versioned outside this repository and are not part of the public open-source release internals.
- The release script is interactive. It is useful for guided manual releases, but not a complete unattended pipeline by itself.