Align release metadata and notes with upstream style

Author: a-a-k

.github/workflows/release.yml

@@ -41,13 +41,31 @@ jobs:
           helm push "$chart_file" "oci://ghcr.io/${repo_owner}/charts"
 
       - name: Publish GitHub release
-        uses: softprops/action-gh-release@v2
-        with:
-          prerelease: ${{ startsWith(github.ref_name, 'v0.') }}
-          files: |
-            dist/charts/*.tgz
-            dist/assets/*.tgz
-            dist/stack-manifest.json
-            dist/compatibility-matrix.json
-            dist/SHA256SUMS.txt
-            dist/sbom.cdx.json
+        shell: bash
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          title="$(python - <<'PY'
+          import json
+          from pathlib import Path
+          print(json.loads(Path("dist/release-manifest.json").read_text(encoding="utf-8"))["title"])
+          PY
+          )"
+          mapfile -t assets < dist/release-assets.txt
+          args=()
+          for asset in "${assets[@]}"; do
+            args+=("dist/${asset}")
+          done
+          if gh release view "${GITHUB_REF_NAME}" >/dev/null 2>&1; then
+            gh release upload "${GITHUB_REF_NAME}" "${args[@]}" --clobber
+            gh release edit "${GITHUB_REF_NAME}" --title "${title}" --notes-file dist/release-notes.md
+          else
+            gh release create "${GITHUB_REF_NAME}" \
+              --verify-tag \
+              --title "${title}" \
+              --notes-file dist/release-notes.md \
+              "${args[@]}"
+          fi
+          release_id="$(gh release view "${GITHUB_REF_NAME}" --json id --jq .id)"
+          gh api "repos/${GITHUB_REPOSITORY}/releases/${release_id}" -X PATCH -F prerelease=false -F draft=false >/dev/null

README.md

@@ -18,6 +18,9 @@ A stack release publishes:
 - a packaged asset archive with `collector/`, `dashboards/`, and `examples/`
 - `stack-manifest.json`
 - `compatibility-matrix.json`
+- `release-manifest.json`
+- `release-manifest.schema.json`
+- `release-notes.md`
 - `SHA256SUMS.txt`
 - a CycloneDX SBOM for the packaged release assets
 
@@ -75,3 +78,7 @@ python scripts/tasks.py release-dry-run
 ## Compatibility Notes
 
 The compatibility files in `compat/` are the source of truth for stack-level assertions. The current `0.1.0` bundle is recorded as a `candidate` integration statement backed by upstream release manifests and Sheaft's published compatibility manifest, not as a broader verified operations guarantee.
+
+## License
+
+MIT, see [LICENSE](LICENSE).

RELEASING.md

@@ -2,6 +2,8 @@
 
 This repository releases integration artifacts, not application binaries.
 
+The canonical source of truth is the local `dist/` payload plus `dist/release-manifest.json`. GitHub Releases and OCI chart publication are publishing surfaces around that payload.
+
 ## Release Outputs
 
 Each stack release is expected to publish:
@@ -10,6 +12,9 @@ Each stack release is expected to publish:
 - `mb3r-assets-<version>.tgz`
 - `stack-manifest.json`
 - `compatibility-matrix.json`
+- `release-manifest.json`
+- `release-manifest.schema.json`
+- `release-notes.md`
 - `SHA256SUMS.txt`
 - `sbom.cdx.json`
 

release/v0.1.0.md

@@ -0,0 +1,34 @@
+## mb3r-stack v0.1.0
+
+First public MB3R integration bundle release for the stack-level packaging layer above released Bering and Sheaft artifacts.
+
+### Upstream pins in this bundle
+
+- Bering `v0.1.0` pinned to `ghcr.io/mb3r-lab/bering@sha256:8e8ce6599b43477b0653617e829d41c62a3189d16b60ecb424cca718fc0e2674`
+- Sheaft `v0.1.1` pinned to `ghcr.io/mb3r-lab/sheaft@sha256:eb1ebf9d96c55c5bb29e226e07496d152eb3a66b52dd9d34ba799fa4aef70624`
+
+### What this release publishes
+
+- the `mb3r-otel-addon` OCI-publishable Helm chart
+- the packaged `mb3r-assets` archive with collector snippets, dashboards, and examples
+- `stack-manifest.json`, `compatibility-matrix.json`, and `release-manifest.json`
+- `SHA256SUMS.txt`, `sbom.cdx.json`, and `release-notes.md`
+
+### Compatibility statement
+
+- bundle status is `candidate`, not `verified`
+- compatibility evidence is pinned to the published Bering `v0.1.0` release manifest plus the published Sheaft `v0.1.1` release and compatibility manifests
+- stack-level contracts remain `collectorExport`, `discoveryReport`, `gateDecision`, and `reportPayload` at `v1alpha1`
+- dashboards stay versioned at `1.0.0` for both Bering and Sheaft views
+
+### CI and install surface
+
+- GitHub, GitLab, and Jenkins adapters now default to immutable upstream image references instead of `TODO-*` placeholders
+- example values files ship concrete upstream image tags and digests for local and production-style installs
+- chart metadata and OCI publication now target the canonical `ghcr.io/mb3r-lab/charts` namespace
+
+### Known limits
+
+- this repository owns only the integration bundle, not upstream Bering or Sheaft binaries or source releases
+- compatibility claims are limited to published upstream artifacts and checked-in integration assets
+- broader operational support should remain conservative until this bundle graduates from `candidate` to `verified`