# Release Guide How to ship **dev**, **staging**, and **production** releases of this monorepo. ![Release Workflow Diagram](https://raw.githubusercontent.com/powerhouse-inc/powerhouse/refs/heads/main/release-flow.png) The release pipeline is a single GitHub Action — `.github/workflows/release-branch.yml` — that calls `releases/release.ts` to drive Nx's release tooling. As a developer you only control: 1. **The branch you run it on** — this decides the release **channel**. 2. **The `release_mode` input** — this decides the **semver bump**. You do **not** manually edit `package.json` versions or `CHANGELOG.md` files, **except** in the baseline case described in [Staging — Case 3](#case-3--fresh-staging-line-at-a-non-adjacent-version-baseline-required). Nx writes them, commits them, tags them, and pushes them on every run. > The repo also has `.github/workflows/manual-release.yml` ("Full Managed Release") — it is **deprecated**. Do not use it for normal releases. ## Table of contents - [Channels](#channels) - [How `release_mode` maps to a semver bump](#how-release_mode-maps-to-a-semver-bump) - [Triggering a release](#triggering-a-release) - [Dev releases (main)](#dev-releases-main) - [Staging releases](#staging-releases) - [Case 1 — Fresh staging line, target reachable in one semver step](#case-1--fresh-staging-line-target-reachable-in-one-semver-step-from-main) - [Case 2 — Next prerelease on an existing staging branch](#case-2--next-prerelease-on-an-existing-staging-branch) - [Case 3 — Fresh staging line at a non-adjacent version](#case-3--fresh-staging-line-at-a-non-adjacent-version-baseline-required) - [Production releases](#production-releases) - [Step 1 — Create the production release branch](#step-1--create-the-production-release-branch) - [Step 2 — Update `RELEASE-NOTES.md`](#step-2--update-release-notesmd) - [Step 3 — Trigger the Release Branch workflow](#step-3--trigger-the-release-branch-workflow) - [Step 4 — Wait for the workflow to complete](#step-4--wait-for-the-workflow-to-complete) - [Step 5 — Announce in `#coredev-releases`](#step-5--announce-in-coredev-releases) - [Hot-fix flow](#hot-fix-flow) - [Reference — `RELEASE-NOTES.md` format conventions](#reference--release-notesmd-format-conventions) - [What the release commit contains](#what-the-release-commit-contains) - [After the release job](#after-the-release-job) - [Troubleshooting](#troubleshooting) - [Quick reference](#quick-reference) --- ## Channels | Branch | Channel | npm dist-tag | Version shape | | ---------------------------- | ---------- | ------------ | ----------------- | | `main` | dev | `dev` | `X.Y.Z-dev.N` | | `release/staging/