chore(release): version-lock CLI to bundle for v0.2.0-beta.1 (#316)

* chore(release): version-lock CLI to bundle for v0.2.0-beta.1

Prep for the first bundle-versioned release. Aligns the CLI to the bundle
version, points the release workflow at the bundle tag, and enforces the
versioning scheme from
#27.


Signed-off-by: Kyle Hounslow <kylhouns@amazon.com>

Author: kylehounslow

.github/workflows/release-drafter.yml

@@ -3,7 +3,7 @@ name: Release Workflow
 on:
   push:
     tags:
-      - "cli-installer-v*"
+      - "v*"
 
 jobs:
   release-to-npm:
@@ -17,6 +17,52 @@ jobs:
       - name: Checkout
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
 
+      # Enforces the version scheme from
+      # https://github.com/opensearch-project/observability-stack/issues/27:
+      # MAJOR.MINOR.PATCH[-(alpha|beta|rc).N]. The git tag and package.json
+      # version must agree; the CLI clones the stack at `v<package.json version>`.
+      - name: Validate release version
+        id: version
+        run: |
+          set -euo pipefail
+          version=$(jq -r .version aws/cli-installer/package.json)
+          tag_version="${GITHUB_REF_NAME#v}"
+
+          fail() {
+            echo "::error title=Invalid release version::$1"
+            {
+              echo "## ❌ Release rejected"
+              echo ""
+              echo "$1"
+              echo ""
+              echo "Expected scheme: \`vMAJOR.MINOR.PATCH[-(alpha|beta|rc).N]\`"
+              echo "Defined in RFC #27: https://github.com/opensearch-project/observability-stack/issues/27"
+              echo "Examples: \`v0.2.0\`, \`v0.2.0-beta.1\`, \`v1.0.0-rc.2\`"
+              echo ""
+              echo "Pushed git tag: \`${GITHUB_REF_NAME}\` · package.json: \`${version}\`"
+            } >> "$GITHUB_STEP_SUMMARY"
+            exit 1
+          }
+
+          if [[ "$version" != "$tag_version" ]]; then
+            fail "Git tag '${GITHUB_REF_NAME}' does not match package.json version '${version}'. Tag and package.json must agree — the CLI clones the stack at v<package.json version>."
+          fi
+
+          stable_re='^[0-9]+\.[0-9]+\.[0-9]+$'
+          pre_re='^[0-9]+\.[0-9]+\.[0-9]+-(alpha|beta|rc)\.[0-9]+$'
+
+          if [[ "$version" =~ $stable_re ]]; then
+            echo "dist_tag=latest" >> "$GITHUB_OUTPUT"
+            echo "is_prerelease=false" >> "$GITHUB_OUTPUT"
+          elif [[ "$version" =~ $pre_re ]]; then
+            echo "dist_tag=${BASH_REMATCH[1]}" >> "$GITHUB_OUTPUT"
+            echo "is_prerelease=true" >> "$GITHUB_OUTPUT"
+          else
+            fail "Version '${version}' is off-scheme. Only MAJOR.MINOR.PATCH or MAJOR.MINOR.PATCH-(alpha|beta|rc).N are allowed."
+          fi
+
+          echo "✅ Release version '${version}' valid (dist-tag: $(grep '^dist_tag=' "$GITHUB_OUTPUT" | cut -d= -f2))." >> "$GITHUB_STEP_SUMMARY"
+
       - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
         with:
           node-version: '24'
@@ -33,10 +79,11 @@ jobs:
 
       - name: Publish to npm
         working-directory: aws/cli-installer
-        run: npm publish
+        run: npm publish --tag "${{ steps.version.outputs.dist_tag }}"
 
       - name: Release on Github
         uses: softprops/action-gh-release@3bb12739c298aeb8a4eeaf626c5b8d85266b0e65 # v2
         with:
           draft: false
+          prerelease: ${{ steps.version.outputs.is_prerelease == 'true' }}
           generate_release_notes: true

.gitignore

@@ -3,6 +3,7 @@
 *.code-workspace
 __pycache__
 .dev
+.idea
 .venv
 venv
 node_modules

RELEASING.md

@@ -0,0 +1,33 @@
+# Releasing
+
+How maintainers cut a release of observability-stack. Versioning follows the scheme in [RFC #27](https://github.com/opensearch-project/observability-stack/issues/27).
+
+## Versioning
+
+Independent bundle semver: `vMAJOR.MINOR.PATCH[-(alpha|beta|rc).N]`. Upstream component versions (OpenSearch, Data Prepper, OTel Collector, Prometheus) are pinned in `.env` and listed in the release notes, not encoded in the tag.
+
+- Prerelease: `v0.2.0-beta.1`, `v1.0.0-rc.2`. Publishes to an npm dist-tag matching the qualifier (`alpha`/`beta`/`rc`), so bare `npx` stays on the stable `latest`.
+- Stable: `v0.2.0`. Publishes to `latest`.
+- `v1.0.0` is a deliberate major/GA decision (a breaking change or a GA milestone), not an automatic follow-on to the first stable.
+
+The `release-drafter.yml` workflow rejects any tag that does not match the scheme, or whose version disagrees with `aws/cli-installer/package.json`.
+
+## The CLI ships with the bundle
+
+The CLI (`aws/cli-installer`, published to npm as `@opensearch-project/observability-stack`) is version-locked to the bundle. Its managed deploy clones the stack at the git tag matching its own version (`v${PKG_VERSION}`). So the CLI `package.json` version, the git tag, and the release must all agree. There is no CLI-only release path.
+
+## Cutting a release
+
+1. Open a PR that sets `aws/cli-installer/package.json` to the target version (e.g. `0.2.0-beta.1`). Sign commits for DCO (`git commit -s`). Get a maintainer review and merge to `main`.
+2. Tag the merged commit and push it:
+   ```
+   git tag v0.2.0-beta.1 <sha>
+   git push upstream v0.2.0-beta.1
+   ```
+   The tag is the release trigger. Merging alone publishes nothing.
+3. The `release-to-npm` job pauses on the `release-approval` environment. A required reviewer, who cannot be the release author, opens the workflow run and approves the deployment.
+4. On approval, the workflow validates the version, runs tests, publishes the CLI to the correct npm dist-tag, and drafts the GitHub release. Fill in the release notes with the component-version matrix from `.env`.
+
+## Promoting a prerelease to stable
+
+Once the prerelease is validated and any fixes are merged, repeat the flow with the qualifier dropped: set `package.json` to `0.2.0`, tag `v0.2.0`, approve. It publishes to `latest`.

aws/cli-installer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensearch-project/observability-stack",
-  "version": "0.1.2",
+  "version": "0.2.0-beta.1",
   "description": "CLI for the Observability Stack",
   "type": "module",
   "bin": "./bin/cli-installer.mjs",

aws/cli-installer/src/ec2-demo.mjs

@@ -28,10 +28,11 @@ const { version: PKG_VERSION } = require('../package.json');
 const TAG_KEY = 'observability-stack:pipeline-name';
 const INSTANCE_TYPE = 't3.xlarge';
 
-// The stack revision the EC2 instance clones. Defaults to the git tag matching
-// this CLI release so a pinned CLI deploys a pinned stack (no drift from main
-// HEAD at boot time). Override with OBS_STACK_REF for development.
-const STACK_REF = process.env.OBS_STACK_REF || `cli-installer-v${PKG_VERSION}`;
+// The stack revision the EC2 instance clones. Defaults to the bundle release
+// tag matching this CLI version (CLI is version-locked to the bundle), so a
+// pinned CLI deploys the matching pinned stack (no drift from main HEAD at boot
+// time). Override with OBS_STACK_REF for development.
+const STACK_REF = process.env.OBS_STACK_REF || `v${PKG_VERSION}`;
 
 function tags(pipelineName, extra = {}) {
   return [

aws/cli-installer/test/unit.test.mjs

@@ -160,10 +160,11 @@ describe('EC2 demo buildUserData', () => {
     assert.ok(decoded.includes('docker-buildx'));
   });
 
-  it('pins the stack clone to a ref instead of tracking main HEAD', () => {
+  it('pins the stack clone to the bundle release tag instead of tracking main HEAD', () => {
     const decoded = Buffer.from(_buildUserData(cfg), 'base64').toString();
     assert.ok(decoded.includes('--branch "$OBS_STACK_REF"'));
-    assert.ok(decoded.includes('cli-installer-v'));
+    // CLI is version-locked to the bundle: clone ref is `v<PKG_VERSION>`.
+    assert.ok(/OBS_STACK_REF="v\d/.test(decoded));
   });
 
   it('clears COMPOSE_PROFILES so local-backend services are pruned in managed mode', () => {