Skip to content

Releasing TALOS

Versioning

TALOS follows Semantic Versioning (MAJOR.MINOR.PATCH).

When to Bump

Increment When Examples
MAJOR Breaking changes to MQTT topics, payload schemas, REST API contracts, or database schema requiring migration Renaming an MQTT topic, changing a payload field type, removing an API endpoint
MINOR New features that are backward-compatible New MQTT message type, new API endpoint, new dashboard feature, new agent capability
PATCH Bug fixes, documentation updates, dependency updates Fix Doppler calculation error, update TLE parsing, security patch

The version is defined in pyproject.toml under [project] version.

Release Process

1. Prepare the Release

Ensure all tests pass:

make lint && make typecheck && make test
./tests/test_integration/test_e2e_docker.sh

2. Update the Changelog

Edit docs/CHANGELOG.md:

  • Move items from [Unreleased] to a new version section
  • Add the release date
  • Ensure all notable changes are documented under the correct category (Added, Changed, Deprecated, Removed, Fixed, Security)

3. Update the Version

Edit pyproject.toml:

[project]
version = "0.2.0"

4. Commit the Release

git add pyproject.toml docs/CHANGELOG.md
git commit -m "release: v0.2.0"

5. Create a Git Tag

git tag -a v0.2.0 -m "Release v0.2.0"
git push origin main --tags

6. Build Docker Images

docker build -t talos-core:0.2.0 -f core/Dockerfile .
docker build -t talos-agent:0.2.0 -f agent/Dockerfile .

Tag as latest:

docker tag talos-core:0.2.0 talos-core:latest
docker tag talos-agent:0.2.0 talos-agent:latest

7. Push to Registry

docker push registry.gitlab.com/pierros/talos/talos-core:0.2.0
docker push registry.gitlab.com/pierros/talos/talos-core:latest
docker push registry.gitlab.com/pierros/talos/talos-agent:0.2.0
docker push registry.gitlab.com/pierros/talos/talos-agent:latest

Docker Image Tags

Each release produces the following Docker images:

Image Contents
talos-core:<version> Core API (FastAPI) and Mission Director (both run from the same image with different entry points)
talos-agent:<version> Agent edge client

Tag Convention

Tag Meaning
0.1.0 Immutable release tag; always points to the same build
latest Mutable tag; points to the most recent release
main Built from the main branch tip (CI only, not for production)

Branch Strategy

Branch Purpose Protection
main Stable releases; always deployable Protected: requires PR review, passing CI
feature/* New features under development None; merge to main via PR
fix/* Bug fixes None; merge to main via PR
release/* Release preparation (optional, for complex releases) None

Workflow

  1. Create a feature branch from main: git checkout -b feature/my-feature
  2. Develop and commit with conventional commit messages (see CONTRIBUTING.md)
  3. Open a pull request targeting main
  4. CI runs lint, type check, and tests
  5. After review and approval, merge to main
  6. Tag the release on main when ready

Pre-Release Checklist

  • [ ] All tests pass (make lint && make typecheck && make test)
  • [ ] End-to-end tests pass (./tests/test_integration/test_e2e_docker.sh)
  • [ ] Changelog updated with all notable changes
  • [ ] Version bumped in pyproject.toml
  • [ ] No hardcoded secrets or development-only settings in committed code
  • [ ] Docker images build successfully
  • [ ] Documentation is up to date (ARCHITECTURE.md, DEVELOPMENT.md)