[RFC] Versioning Strategy for observability-stack

[kylehounslow]

RFC: Versioning Strategy for observability-stack

Summary

Defines a versioning scheme for observability-stack releases that anchors to the OpenSearch version and uses semver pre-release qualifiers to signal maturity.

Motivation

observability-stack bundles multiple components (OpenSearch, OpenSearch Dashboards, Data Prepper, OTel Collector) into a single docker-compose experience. We need a versioning scheme that:

• Makes it clear which OpenSearch version a release is built against
• Signals release maturity (alpha, beta, rc, stable)
• Allows fast iteration on main without breaking tagged releases
• Follows semver conventions so tooling handles it correctly

Proposal

Version Format

{opensearch-version}-{qualifier}.{iteration}

Examples:

• 3.5.0-alpha.1 — first alpha release against OpenSearch 3.5.0
• 3.5.0-alpha.2 — second alpha, bug fixes or component updates
• 3.5.0-beta.1 — feature complete, broader testing
• 3.5.0-rc.1 — release candidate, final validation
• 3.5.0 — stable release

Lifecycle

alpha  →  beta  →  rc  →  stable

Not every stage is required. A release can skip from alpha to rc if confidence is high.

What each stage means

Stage	Meaning
alpha	Core functionality works. Known gaps. Breaking changes possible.
beta	Feature complete for the release scope. No known breaking issues.
rc	Release candidate. Final validation, docs complete.
stable	Production ready. Fully tested, documented, supported.

Component versions

Individual component versions (Data Prepper, OTel Collector, etc.) are not encoded in the tag. Instead:

• .env file at each tagged commit has all pinned component versions (this is already the case today)
• GitHub release notes list the full component version matrix
• docker-compose.yml references .env variables, so the tag is a complete snapshot

Current .env structure (relevant lines):

OPENSEARCH_VERSION=3.5.0
OPENSEARCH_DASHBOARDS_VERSION=3.5.0
DATA_PREPPER_VERSION=2.14.0
OTEL_COLLECTOR_VERSION=0.146.1
PROMETHEUS_VERSION=v3.8.1

No separate VERSIONS file needed — .env already serves this purpose.

Git tags and branches

• main — latest development, untagged, moves fast
• Tags — immutable snapshots of known-good combinations (e.g. v3.5.0-alpha.1)
• Tags prefixed with v per convention

Docker image tags

• latest — always points to main
• 3.5.0-alpha.1 — matches the git tag (without v prefix)
• No stable or latest-stable alias until we have a stable release

When OpenSearch version bumps

When OpenSearch releases 3.6.0:

• New releases start at 3.6.0-alpha.1
• Existing 3.5.0 releases can still receive patches (e.g. 3.5.0-alpha.3) if needed
• No obligation to support multiple OpenSearch versions simultaneously at this stage

Open Questions

1. Graduation criteria — what specifically must be true to move from alpha → beta → stable?
2. Should we automate version bumps via CI (e.g. Renovate/Dependabot for component images in .env)?
3. Do we maintain releases across multiple OpenSearch versions (e.g. 3.5.0-alpha.2 and 3.6.0-alpha.1 simultaneously)?

References

• Semantic Versioning 2.0.0
• OpenSearch release schedule