[RFC] Versioning Strategy for observability-stack

RFC: Versioning Strategy for observability-stack

Summary

Defines a versioning scheme for observability-stack releases using independent semver. Upstream component versions (OpenSearch, Data Prepper, OTel Collector, etc.) are pinned in .env and documented in release notes.

Motivation

observability-stack bundles multiple components into a single docker-compose experience. We need a versioning scheme that:

Makes it clear which components and versions a release contains
Signals release maturity (alpha, beta, rc, stable)
Allows fast iteration on main without breaking tagged releases
Follows standard semver so tooling (npm, Helm, Docker, Renovate) handles it correctly
Decouples our release cadence from any single upstream dependency

Precedent

Surveyed how similar infrastructure bundles version themselves:

Project	Bundle version	Upstream tracking
kube-prometheus-stack	`84.4.0` (independent)	`appVersion: v0.90.1`
grafana/docker-otel-lgtm	`v0.26.0` (independent)	Release notes
SigNoz	`v0.121.0` (independent)	Release notes
OpenObserve	`v0.80.1` (independent)	Release notes
Coroot	`v1.19.7` (independent)	Release notes
OTel Demo	`2.2.0` (independent)	Release notes
ClickStack	No bundle version	`.env` only

All use independent semver with upstream versions tracked separately. The closest analog is kube-prometheus-stack, which bundles Prometheus, Grafana, and an operator using independent chart versioning with appVersion pointing at the primary upstream component.

The only counter-example is the OpenSearch plugin convention (4-segment like 2.9.0.45), and OpenSearch's own RELEASING.md notes an open proposal to drop it.

Proposal

Version Format

Standard semver 2.0.0: vMAJOR.MINOR.PATCH[-qualifier.N]

Examples:

v0.1.0-alpha.1 — early alpha
v0.1.0-beta.1 — feature complete, broader testing
v0.1.0-rc.1 — release candidate
v0.1.0 — first stable
v0.1.1 — patch (CVE, bug fix, drop-in component bump)
v0.2.0 — minor (new feature, non-breaking)
v1.0.0 — major (breaking config changes, OpenSearch major bump requiring user action)

Initial Release

The first release will be v0.2.0-alpha.1. This starts the bundle version one minor above the CLI's current npm version (0.1.1), so aligning the CLI to the bundle version going forward is a forward bump rather than a regression.

Lifecycle

alpha → beta → rc → stable

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

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.

Bumping Rules

PATCH (v0.1.0 → v0.1.1): bug fixes, CVE patches, drop-in component version bumps
MINOR (v0.1.1 → v0.2.0): new features, new OpenSearch minor version, new optional components, non-breaking config additions
MAJOR (v0.x → v1.0.0): breaking config changes, removal of deprecated features, major OpenSearch version bumps requiring user action

Example scenarios:

If observability-stack is currently on v0.1.0:

OpenSearch 3.6.0 → 3.6.1 (drop-in): v0.1.0→v0.1.1
New default dashboard we built, OpenSearch unchanged: v0.1.0→v0.1.1
Prometheus CVE fix: v0.1.0→v0.1.1independent of OpenSearch state
OpenSearch 3.6 → 3.7 (new minor): v0.1.0→ v0.2.0, even if our observability-stack changes are minimal
OpenSearch 3.x → 4.0: v0.1.0→v1.0.0

Component Versions

Upstream versions are not encoded in the tag. They are pinned in .env:

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

Release notes explicitly list the component matrix, e.g. "v0.1.0 — built against OpenSearch 3.6.0, Data Prepper 2.14.0, OTel Collector 0.146.1".

Git Tags and Branches

main: latest development, untagged, moves fast
Tags: immutable snapshots (e.g. v0.1.0)
v prefix per common convention

Branching follows Single Repo Artifacts Branching: next release always on main, no long-lived patch branches. Can adopt distribution-style branching later if we need to maintain multiple OpenSearch-anchored lines simultaneously.

When OpenSearch Releases a New Version

Test the bundle against the new version
Update .env on main
Cut a new release: minor bump if drop-in, major bump if it requires user action

We don't automatically cut a release on every OpenSearch patch. A new bundle release implies we've validated it.

Docker Images

Today this repo does not publish Docker images. All image: references in docker-compose.yml point to upstream registries (otel/opentelemetry-collector-contrib, prom/prometheus, opensearchproject/data-prepper, etc.). Custom components (the canary service, example agents) are built locally via docker-compose build.

If we start publishing Docker images in the future (e.g. publishing the canary or example agents to a public registry for easier consumption), they will follow the bundle version tag:

Image tag matches the bundle git tag without the v prefix: bundle v0.1.0 → image 0.1.0
latest points to main
Multi-arch builds (amd64, arm64) where applicable

Components with independent release lifecycles (for example, if the canary or an example agent becomes a standalone product with its own cadence) can opt into separate versioning with a documented reason.

Scope

This RFC governs the observability-stack bundle tag. Artifacts that ship with the bundle or install it are aligned with the bundle version:

@opensearch-project/observability-stack (npm CLI): aligned with bundle version. A bundle release is also a CLI release at the same version, so npx @opensearch-project/observability-stack@0.1.0 installs the same components that docker compose up at tag v0.1.0 does. This ensures the CLI and docker-compose paths produce the same snapshot of pinned versions. Alignment becomes especially important once the CLI supports bootstrapping the open-source (docker-compose) stack, not just the AWS managed path.
Docker images built from this repo (canary, example agents, if published): inherit the bundle version with v stripped (v0.1.0 → 0.1.0).
Helm chart (when added): Chart version tracks the bundle version. appVersion references the primary upstream (OpenSearch) version per Helm convention.

Artifacts with fully independent lifecycles stay separate:

Claude Code plugin: has its own release workflow; not part of the bundle snapshot.
Standalone components (e.g. if the canary or an example agent becomes a standalone product): can opt out with a documented reason.

Open Questions

Graduation criteria: what specifically must be true to move from alpha → beta → stable? (Suggest adapting OpenSearch entrance/exit criteria.)
Automation: wire up Renovate/Dependabot to propose .env component bumps? CI to run e2e tests on tag push before release?
Registry for custom images: when we do publish (canary, examples), which registry? Docker Hub under opensearchproject/*, GitHub Container Registry, or both?

Description