# Arbor Release Runbook (Publish Everywhere)

This runbook ensures Arbor releases propagate across all distribution channels — not only GitHub Releases.

## Release channels covered

- GitHub Release assets (multi-platform CLI binaries)
- crates.io (workspace crates)
- GHCR container image (`ghcr.io/anandb71/arbor`)
- VS Code Marketplace extension
- Open VSX extension
- Homebrew formula (`packaging/homebrew/arbor.rb`)
- Scoop manifest (`packaging/scoop/arbor.json`)
- npm wrapper (`packaging/npm/`)
- MCP release note enrichment snippets

## Required repository secrets

Configure these in **Settings → Secrets and variables → Actions**:

- `CARGO_REGISTRY_TOKEN` — crates.io publishing token
- `VSCE_PAT` — VS Code Marketplace publisher token (optional but recommended)
- `OVSX_PAT` — Open VSX publisher token (optional but recommended)
- `NPM_TOKEN` — npm publish token for `@anandb71/arbor-cli` wrapper (optional but recommended)

> Extension publishing requires at least one of `VSCE_PAT` or `OVSX_PAT`.
>
> npm wrapper publishing requires `NPM_TOKEN`.

## Workflow map

- `.github/workflows/release.yml`
  - Trigger: tag push (`v*`)
  - Builds cross-platform CLI binaries (5 targets)
  - Publishes crates to crates.io
  - Creates GitHub Release and uploads assets

- `.github/workflows/ghcr.yml`
  - Trigger: GitHub Release published
  - Builds and publishes GHCR image (tag + latest)

- `.github/workflows/vscode-marketplace.yml`
  - Trigger: GitHub Release published or manual dispatch
  - Compiles extension
  - Resolves extension version from release tag (`vX.Y.Z` → `X.Y.Z`) unless manually overridden
  - Publishes packaged VSIX to VS Code Marketplace and/or Open VSX

- `.github/workflows/mcp-release-adoption.yml`
  - Trigger: GitHub Release published
  - Appends MCP quick-install snippets to release notes

- `.github/workflows/arbor-pr-bot.yml`
  - Trigger: Pull request events
  - Runs `analyze-impact` and posts blast-radius governance comment
  - Gracefully posts fallback context when markdown report generation fails

- `.github/workflows/npm-publish.yml`
  - Trigger: GitHub Release published or manual dispatch
  - Publishes npm wrapper package from `packaging/npm/`

## Recommended release sequence

1. Ensure `CHANGELOG.md` and release notes docs are updated.
2. Ensure workspace version and internal crate dependency versions are aligned.
3. Create and push a release tag:
   - `vX.Y.Z`
4. Wait for all workflows to complete:
   - Release
   - GHCR
   - VS Code Extension Publish
   - MCP Release Adoption Notes

## Versioning conventions

- Git tag format: `vX.Y.Z`
- Cargo crates: `X.Y.Z`
- VS Code extension package: `X.Y.Z` (derived from release tag automatically in release-triggered publish)

## Verification checklist

After release completion, verify:

- GitHub Releases contains all CLI assets
- `cargo install arbor-graph-cli --version X.Y.Z` succeeds
- `docker pull ghcr.io/anandb71/arbor:latest` succeeds
- VS Code Marketplace listing shows latest extension version
- Open VSX listing shows latest extension version
- Release notes include MCP install snippet section
- Arbor PR Bot posts impact comments on new PRs (or explicit fallback comment with run URL if analysis fails)
