The Release Process and Release Trains

A reviewed, compatibility-safe change merged to main is not yet released. Between your merged PR and a user running the fix lies the release machinery: a schedule, a release manager, a tracking issue, a build-and-bundle pipeline, and generated release notes. Unlike the Apache model, there is no [VOTE] email and no formal release vote. Release decisions happen openly in a dedicated repo, opensearch-build, coordinated through public GitHub issues. This chapter is how OpenSearch ships, and — the part you actually need — exactly what you must do to get a fix into a given release.

The opensearch-build Repo Is the Release Control Plane

The core engine lives in opensearch-project/OpenSearch, but a release is more than the engine. OpenSearch ships as a bundle: the core distribution plus the standard plugins (security, k-NN, SQL, alerting, index-management, ml-commons, observability, and the rest), each from its own repo, assembled into a single coherent product at one version.

That assembly, the schedule, and the per-release coordination live in opensearch-project/opensearch-build:

# The control plane (browse, don't clone unless you're release-managing):
# github.com/opensearch-project/opensearch-build
# Look for: the release schedule, the "Release version X.Y.Z" tracking issues,
# and the per-version manifests.

The key mental shift from Apache: the "release decision" is not a moment (an email vote passing). It is a process that becomes visibly done when the release-readiness issue's checklist is complete and the pipeline has produced validated artifacts.

Release Trains: Major, Minor, Patch

OpenSearch ships on trains — scheduled departures you either make or wait for.

main is the 3.x development line. 2.x is the active maintenance line (gets backported fixes and minors). 1.x is legacy (security/critical fixes only). The train you can catch depends on what your change is: a feature rides a minor off main; a bug fix can ride a patch on a maintenance branch via backport.

Note: "Train" is not just a metaphor for cadence — it is a metaphor for the cutoff. A train leaves on a schedule whether or not your change is aboard. Miss the merge-and- backport deadline for a release and your fix waits for the next departure.

The Release Manager and the Readiness Issue

Each release has a release manager — a person (rotating, from the community/maintainers) who owns shepherding that version out. They are coordinator, not dictator: the work is done by each component's maintainers; the release manager tracks it.

Their primary instrument is the release-readiness tracking issue in opensearch-build, which aggregates, per component:

• Is the component's release branch cut and code-frozen?
• Are all targeted PRs merged and backported by the cutoff?
• Are the CHANGELOG.md entries in place (they become the release notes)?
• Do the integration tests / BWC tests / packaging tests pass in the bundle?
• Is the documentation (the separate documentation-website repo) updated?
• Are there any release-blocking issues open? (See issue-roadmap stage 12.)

The release ships when this checklist is green across components. That is the "vote" — conducted in checkboxes, in public, on a GitHub issue.

The Release Pipeline

flowchart TD
    A[Changes merged to main and backport branches] --> B[Release branch cut / code freeze]
    B --> C[Per-component build in opensearch-build]
    C --> D[Assemble the bundle: core + standard plugins at one version]
    D --> E[Version bumps applied: 3.x.0]
    E --> F[RC build produced]
    F --> G[Validation: integ tests, BWC, packaging, smoke]
    G -->|Issues found| H[Fix, backport, new RC]
    H --> F
    G -->|Clean| I[Release notes generated from CHANGELOG + PRs]
    I --> J[Documentation-website sync]
    J --> K[GA release: artifacts published, announcement]
    K --> L[Backport branches and main keep moving]

Reading the pipeline:

1. Code freeze / release branch. At the cutoff, a release branch is cut. After this, only approved fixes land for that version — this is the firm edge of the train.
2. Build and bundle. opensearch-build builds each component at the manifest-pinned ref and assembles them into one distribution.
3. Version bumps. Versions are incremented (v3.x.0), including the internal Version constants the BWC machinery keys off (see maintainer-mindset).
4. RC and validation. Release candidate builds run the full validation: integration, backward-compatibility and rolling-upgrade tests (from qa/), packaging (deb/rpm/ docker/archives), and smoke tests. A failure spawns a fix → backport → new RC loop.
5. Release notes. Generated from the accumulated CHANGELOG.md entries and PR metadata — which is precisely why every PR must add a CHANGELOG line in the right section.
6. Docs sync. The documentation-website repo is updated so opensearch.org/docs matches the release.
7. GA. Artifacts are published and the release is announced.

CHANGELOG → Release Notes

This is the most direct connection between your PR and the release. Every PR to the core repo adds a one-line entry to CHANGELOG.md under the unreleased section, categorized:

## [Unreleased 3.x]
### Added
- Add `include_unloaded_segments` to the nodes stats API ([#NNNN](https://github.com/opensearch-project/OpenSearch/pull/NNNN))
### Changed
### Fixed
- Fix DiskThresholdDecider off-by-one for relocating shards ([#MMMM](https://github.com/opensearch-project/OpenSearch/pull/MMMM))
### Deprecated
### Removed
### Security

At release time, the entries under the unreleased section for the version being cut are rolled up into the human-readable release notes. Consequences for you:

• A missing CHANGELOG entry means your change is invisible in the release notes — and the precommit/PR checks will usually catch the omission first.
• The section matters. On main your entry sits under [Unreleased 3.x]. When you backport to 2.x, the entry must move to [Unreleased 2.x] so it lands in the right release's notes. Mis-sectioning is a common backport-PR review comment (see GitHub review).

What You Must Do to Get a Fix Into a Given Release

This is the operational checklist. To land a fix in release X.Y.Z:

• Merge to main before the cutoff. The fix has to be in main (reviewed, green CI, CHANGELOG entry) before the release branch is cut for the train you want.
• Add the backport label for every maintenance line that needs it (e.g. backport 2.x, and backport 1.x if applicable) — at or before merge, so the backport bot opens the backport PR.
• Land the backport PR before the cutoff for that line's release. A backport that misses the cutoff misses the train, even if main made it.
• Put the CHANGELOG entry in the correct section on both main and the backport.
• Watch the release-readiness issue in opensearch-build for the target version; if your change is release-blocking, make sure it's tracked there.

# Concretely, for a fix you want in the next 2.x patch:
# 1) Open the PR against main, with a CHANGELOG entry under [Unreleased 3.x].
# 2) Add the label `backport 2.x` to the PR.
# 3) After it squash-merges to main, the bot opens a backport PR against 2.x.
# 4) Move the CHANGELOG entry to [Unreleased 2.x] on the backport, get it reviewed and merged.
# 5) Confirm it's listed on the release-readiness issue for the target 2.x.Z version.

Warning: The two failure modes that cost contributors a release: (1) merging to main but forgetting the backport label, so the fix never reaches the maintenance line; and (2) the backport PR conflicting and sitting unresolved past the cutoff. Add the label early and resolve backport conflicts promptly. See release-blocking issues for the highest- stakes version of this.

Prove You Understand This

1. Which repo is the release control plane, and what does a release-readiness issue track?
2. There is no [VOTE] email — so what is the artifact that signals a release is ready to ship?
3. Distinguish major / minor / patch trains by branch, contents, and BWC guarantee. Which train can carry a new feature?
4. Trace your CHANGELOG entry from PR to release notes, including what changes when you backport to 2.x.
5. You have a one-line bug fix you need in the next 2.x patch release. List, in order, every step from opening the PR to confirming it's in the release.
6. Name the two most common ways a contributor's fix misses the train despite being merged to main.

Next: The TSC and Project Governance — who sets the direction the trains run on.