Skip to content

Versioning & Releases

This project follows a structured release strategy that balances stability with ongoing development.

Semantic Versioning

We use Semantic Versioning (MAJOR.MINOR.PATCH) for all tagged releases.

  • MAJOR – breaking changes
  • MINOR – new features, backwards compatible
  • PATCH – bug fixes and internal improvements

Example: 1.2.3 means the 3rd patch release of the 2nd minor version of the 1st major version.

Development Builds from main

Every push to the main branch automatically builds a Docker image and publishes it with the :main tag.

Use this tag for development environments:

ghcr.io/openwallet-foundation-labs/eudiplo:main

⚠️ main is always moving and may contain untagged or unreleased features.

Stable Releases

Stable releases are published via GitHub tags and follow semantic versioning. Each release creates both a versioned tag and updates the :latest tag:

ghcr.io/openwallet-foundation-labs/eudiplo:1.2.3
ghcr.io/openwallet-foundation-labs/eudiplo:latest

The :latest tag always points to the most recent stable release and is recommended for production use.

Pre-Releases

Optionally, pre-release tags such as 1.3.0-alpha.1 may be published for testing upcoming features:

ghcr.io/openwallet-foundation-labs/eudiplo:1.3.0-alpha.1

Release Automation

Releases are managed using semantic-release. It:

  • Analyzes commit messages
  • Determines the next version
  • Publishes a GitHub release
  • Pushes Docker images

Make sure to follow the Conventional Commits specification when contributing to ensure proper versioning.

Summary

Tag Source Use Case
main main branch Development
latest GitHub release Production (Latest)
x.y.z (e.g. 1.2.3) GitHub release Specific Version
x.y.z-alpha.N GitHub pre-release Feature Preview / RC

Backward Compatibility Policy

  • Breaking changes only in major versions. API field renames, removed endpoints, changed configuration formats, and new required environment variables are only introduced in major releases.
  • Deprecate before removing. Where feasible, features are deprecated in a minor release before being removed in the next major.
  • Database migrations are automatic. Schema changes are applied by the migration system on startup. No manual SQL is required.
  • Migration guides for every major version. Each major release includes a step-by-step migration guide covering all required actions.
  • If it breaks in a minor/patch, it's a bug. If you experience a breaking change outside of a major release, please report it.

Breaking Change Checklist (for contributors)

When introducing a breaking change, ensure:

  • The commit message includes BREAKING CHANGE: in the footer (triggers major version bump)
  • The PR description lists all affected endpoints, fields, and environment variables
  • The migration guide is updated with upgrade steps
  • The .env.example is updated if environment variables changed