From 866e0fecafa0ab9c391e5f7516029a0a8d18179e Mon Sep 17 00:00:00 2001
From: Brian O'Kelley <bokelley@scope3.com>
Date: Tue, 26 May 2026 11:56:18 -0400
Subject: [PATCH] ci: use release-please manifest prerelease config

---
 .github/workflows/release-please.yml |  3 ++-
 PYPI_SETUP.md                        |  3 +++
 RELEASING.md                         | 14 ++++++++++++++
 3 files changed, 19 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/release-please.yml b/.github/workflows/release-please.yml
index e9e0ac48c..0d6cf7225 100644
--- a/.github/workflows/release-please.yml
+++ b/.github/workflows/release-please.yml
@@ -23,7 +23,8 @@ jobs:
         id: release
         if: ${{ github.event_name != 'workflow_dispatch' || inputs.publish != true }}
         with:
-          release-type: python
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
 
       - name: Checkout release PR
         if: ${{ steps.release.outputs.prs_created == 'true' }}
diff --git a/PYPI_SETUP.md b/PYPI_SETUP.md
index d5e4d9def..8a2abdeaa 100644
--- a/PYPI_SETUP.md
+++ b/PYPI_SETUP.md
@@ -75,6 +75,9 @@ Versions are managed automatically by Release Please:
 - `feat:` commits → minor version bump (0.1.0 → 0.2.0)
 - `fix:` commits → patch version bump (0.1.0 → 0.1.1)
 - `feat!:` or `BREAKING CHANGE:` → major bump (pre-1.0: minor)
+- During a beta line (`X.Y.Z-beta.N`), releasable commits increment the beta
+  counter only (`X.Y.Z-beta.N+1`) because the workflow uses manifest-mode
+  Release Please config.
 
 ## Verification
 
diff --git a/RELEASING.md b/RELEASING.md
index 2414254ae..ab0c51470 100644
--- a/RELEASING.md
+++ b/RELEASING.md
@@ -182,6 +182,20 @@ We follow [Semantic Versioning](https://semver.org/):
 - **Minor (0.1.0)**: New features, backward compatible
 - **Patch (0.0.1)**: Bug fixes, backward compatible
 
+### Beta Release Behavior
+
+While the current manifest version is a beta (`X.Y.Z-beta.N`), Release Please
+is configured to keep the base version fixed and increment only the beta
+counter. For example:
+
+- `feat:` after `6.3.0-beta.4` -> `6.3.0-beta.5`
+- `fix:` after `6.3.0-beta.4` -> `6.3.0-beta.5`
+
+Do not pass `release-type` directly in `.github/workflows/release-please.yml`;
+that bypasses the manifest configuration. The workflow must use
+`release-please-config.json` and `.release-please-manifest.json` so
+`versioning: prerelease` takes effect.
+
 ### Pre-1.0 Behavior
 
 Before v1.0.0: