docs: channel branches in release workflow + promotion-PR check behavior

- Release workflow examples: comment that channel branches go in the push
  trigger too, and switch the concurrency group to per-ref so a channel
  publish doesn't queue behind / get cancelled by a main release (the lesson
  from dogfooding the next channel).
- Concurrency section: explain the per-ref group and when it matters.
- prereleases.md setup: note existing single-group workflows need the per-ref
  change.
- cli.md: document what 'ci check' shows on channel and promotion PRs.

Author: theoephraim

docs/cli.md

@@ -190,6 +190,8 @@ bumpy ci check --no-fail
 
 Requires `GH_TOKEN` environment variable (automatically available in GitHub Actions).
 
+**On channel and promotion PRs:** for a PR targeting a [prerelease channel](prereleases.md) branch, the comment is channel-aware — it shows the prerelease plan (`-<preid>.x` versions) and the target dist-tag rather than implying a stable release. For a **promotion PR** (a channel branch → `main`, or a graduation like `alpha` → `beta`), the check reads the cycle's already-shipped bump files from `.bumpy/<channel>/` and shows the consolidated stable plan, calling out that merging ends the prerelease cycle. (Feature PRs that _target_ a channel branch are checked against that branch, so only the PR's own new bump files count — see [`--base`](#bumpy-check) on the local `check` command for the equivalent locally.)
+
 ## `bumpy ci plan`
 
 CI command that reports what `ci release` would do, without acting. Outputs JSON to stdout and sets GitHub Actions step outputs so you can conditionally run expensive steps (builds, etc.) only when needed.

docs/github-actions.md

@@ -108,10 +108,15 @@ The recommended release workflow splits version-PR maintenance from publishing i
 name: Bumpy Release
 on:
   push:
+    # Add any prerelease channel branches here too, e.g. [main, next, beta].
+    # See the prerelease channels docs: https://github.com/dmno-dev/bumpy/blob/main/docs/prereleases.md
     branches: [main]
 
 concurrency:
-  group: bumpy-release
+  # Per-branch so a channel (e.g. next) publish doesn't queue behind — or get
+  # cancelled by — a main release. Drop the `-${{ github.ref }}` if you never
+  # add channel branches above.
+  group: bumpy-release-${{ github.ref }}
   cancel-in-progress: false
 
 jobs:
@@ -257,10 +262,15 @@ For simpler setups, you can run everything in a single job. `bumpy ci release` w
 name: Bumpy Release
 on:
   push:
+    # Add any prerelease channel branches here too, e.g. [main, next, beta].
+    # See the prerelease channels docs: https://github.com/dmno-dev/bumpy/blob/main/docs/prereleases.md
     branches: [main]
 
 concurrency:
-  group: bumpy-release
+  # Per-branch so a channel (e.g. next) publish doesn't queue behind — or get
+  # cancelled by — a main release. Drop the `-${{ github.ref }}` if you never
+  # add channel branches above.
+  group: bumpy-release-${{ github.ref }}
   cancel-in-progress: false
 
 jobs:
@@ -321,12 +331,16 @@ Use a concurrency group on your release workflow to prevent overlapping publish
 
 ```yaml
 concurrency:
-  group: bumpy-release
+  # Per-ref: serialize runs within a branch, but let different branches run in
+  # parallel. Drop the `-${{ github.ref }}` if you only ever release from main.
+  group: bumpy-release-${{ github.ref }}
   cancel-in-progress: false # queue rather than cancel — don't skip releases
 ```
 
 This is included in all the workflow examples above.
 
+The `-${{ github.ref }}` matters once you add [prerelease channels](prereleases.md): a single shared group (`bumpy-release`) would make a `next` prerelease publish queue behind — or, with `cancel-in-progress: true`, get cancelled by — a `main` release, even though they touch different dist-tags and never conflict. Per-ref keeps each branch's releases serialized against themselves while letting `main` and `next` proceed independently. If you release only from `main`, the plain `bumpy-release` group is equivalent.
+
 ## Token setup
 
 ### `GH_TOKEN` (required)

docs/prereleases.md

@@ -135,7 +135,9 @@ on:
     branches: [main, next] # add channel branches here
 ```
 
-That's the only workflow change. `bumpy ci release` reads the current branch, looks up the channel in `_config.json`, and behaves accordingly.
+That's the only trigger change. `bumpy ci release` reads the current branch, looks up the channel in `_config.json`, and behaves accordingly.
+
+> **Concurrency:** if your workflow uses a single `concurrency.group` (e.g. `bumpy-release`), make it per-ref (`bumpy-release-${{ github.ref }}`) so a channel publish doesn't queue behind — or get cancelled by — a `main` release. The [recommended release workflow](github-actions.md#release-workflow-recommended-split-jobs) already does this.
 
 > **If your publish job runs in a GitHub Environment with deployment branch restrictions** (the [recommended hardening](github-actions.md#optional-hardening-protection-rules-on-the-publish-environment) restricts it to `main`), add each channel branch to the environment's allowed deployment branches (repo Settings → Environments → publish → Deployment branches). Otherwise the publish job can't run from the channel branch — with npm trusted publishing this means OIDC token requests are rejected and channel publishes fail.