Merge pull request #215 from faetalize/feature/transition-to-pinned-prod-branch

Establish protected production release workflow

Author: faetalize

.github/release-drafter.yml

@@ -0,0 +1,31 @@
+name-template: "v$NEXT_PATCH_VERSION"
+tag-template: "v$NEXT_PATCH_VERSION"
+commitish: production
+change-template: "- $TITLE (#$NUMBER)"
+change-title-escapes: "<*_&"
+
+categories:
+    - title: "Features"
+      labels:
+          - feature
+    - title: "Improvements"
+      labels:
+          - enhancement
+    - title: "Fixes"
+      labels:
+          - bug
+
+include-labels:
+    - feature
+    - enhancement
+    - bug
+
+exclude-labels:
+    - code improvement
+    - documentation
+    - skip-changelog
+
+template: |
+    ## What's New
+
+    $CHANGES

.github/scripts/validate-release-label.mjs

@@ -0,0 +1,31 @@
+import { readFileSync } from "node:fs";
+import process from "node:process";
+
+const classificationLabels = new Set([
+	"feature",
+	"enhancement",
+	"bug",
+	"code improvement",
+	"documentation",
+	"skip-changelog"
+]);
+
+const eventPath = process.env.GITHUB_EVENT_PATH;
+if (!eventPath) {
+	throw new Error("GITHUB_EVENT_PATH is required to validate pull request labels.");
+}
+
+const event = JSON.parse(readFileSync(eventPath, "utf8"));
+const pullRequestLabels = event.pull_request?.labels?.map((label) => label.name) ?? [];
+const classifications = pullRequestLabels.filter((label) => classificationLabels.has(label));
+
+if (classifications.length !== 1) {
+	process.stderr.write(
+		`Pull requests must have exactly one release classification label. Found ${classifications.length}: ${
+			classifications.join(", ") || "none"
+		}. Choose one of: ${[...classificationLabels].join(", ")}.\n`
+	);
+	process.exit(1);
+}
+
+process.stdout.write(`Release classification: ${classifications[0]}\n`);

.github/workflows/merge-gate.yml

@@ -4,6 +4,13 @@ on:
     pull_request:
         branches:
             - main
+            - production
+        types:
+            - opened
+            - reopened
+            - synchronize
+            - labeled
+            - unlabeled
     workflow_dispatch:
 
 jobs:
@@ -14,6 +21,10 @@ jobs:
             - name: Checkout repository
               uses: actions/checkout@v6
 
+            - name: Validate release classification
+              if: github.event_name == 'pull_request' && github.base_ref == 'main'
+              run: node .github/scripts/validate-release-label.mjs
+
             - name: Setup Node.js
               uses: actions/setup-node@v6
               with:

.github/workflows/release-drafter.yml

@@ -0,0 +1,21 @@
+name: Release Drafter
+
+on:
+    push:
+        branches:
+            - main
+    workflow_dispatch:
+
+permissions:
+    contents: write
+    pull-requests: read
+
+jobs:
+    update-release-draft:
+        runs-on: ubuntu-latest
+
+        steps:
+            - name: Update draft release
+              uses: release-drafter/release-drafter@v7
+              with:
+                  config-name: release-drafter.yml

AGENTS.md

@@ -41,11 +41,19 @@ npm run sync-db-types  # Sync Supabase types to src/types/database.types.ts
 
 ### Branching and deployment flow
 
-- Production deploys are published from a dedicated release branch because Cloudflare Pages is configured to deploy a specific branch for releases.
+- Cloudflare Pages production deployments are pinned to the permanent `production` branch.
 - `main` is the ongoing development branch.
-- A release branch is created from `main` after the intended features/fixes have already been merged there.
-- Release-only preparation happens on that release branch first.
-- After the release is deployed, the release branch must be backmerged into `main` so `main` also contains the final version string and in-app changelog for that release.
+- Feature and fix pull requests merge into `main`; do not commit feature work directly to `production`.
+- A temporary `release/vX.Y.Z` branch is created from `main` for the version bump and other release-only preparation. Build the in-app changelog from the current draft GitHub Release, polishing and combining its entries into user-facing copy.
+- Merge the prepared release branch back into `main` with the `skip-changelog` label on the PR, then promote `main` to `production` through a second pull request.
+- Cloudflare deploys the merge into `production`. No release backmerge is needed because release preparation entered `main` before promotion.
+
+### Pull request release classification
+
+- Every pull request targeting `main` must have exactly one release classification label. The merge gate enforces this rule. Promotion pull requests targeting `production` still run the full merge gate but do not need a release classification.
+- Use `feature`, `enhancement`, or `bug` for user-facing changes. Write those pull request titles as concise release-note candidates because Release Drafter uses them directly.
+- Use `code improvement` for internal refactors, `documentation` for documentation-only work, and `skip-changelog` for release preparation or other administrative changes targeting `main`. These labels are excluded from user-facing release notes.
+- Release Drafter runs after merges into `main` and continuously maintains the next draft GitHub Release from included pull requests. The draft targets `production` so publishing it after deployment tags the deployed branch.
 
 ### Pro request edge function slots
 
@@ -54,16 +62,17 @@ npm run sync-db-types  # Sync Supabase types to src/types/database.types.ts
 - `handle-pro-request` and `handle-pro-request-x` are equivalent rotating production slots. The currently released frontend points at one slot, while the other slot is available for the next synced frontend/backend release.
 - Only change the committed `PRO_REQUEST_FUNCTION_NAME` target as part of a new release workflow. Do not change the production target for ordinary feature work, fixes, local testing, or short-lived validation.
 - When a frontend/backend sync release is required, deploy the backend update to the production slot that the currently released frontend is not using, update `PRO_REQUEST_FUNCTION_NAME` to point the new frontend bundle at that slot, then deploy the frontend. This keeps old loaded clients on the old function and new clients on the new function.
-- Use `handle-pro-request-test` for quick backend iteration and local/manual validation. Point `PRO_REQUEST_FUNCTION_NAME` at the test slot only for local test builds or short-lived validation branches; do not leave production release branches pointed at the test slot.
+- Use `handle-pro-request-test` for quick backend iteration and local/manual validation. Point `PRO_REQUEST_FUNCTION_NAME` at the test slot only for local test builds or short-lived validation branches; do not promote a release to `production` while it points at the test slot.
 - Before changing the production target, verify every premium caller uses `PRO_REQUEST_ENDPOINT` rather than hardcoding a function URL.
 
 ### Preparing a new release
 
-- Identify the last release backmerge commit on `main`, then inspect all mainline commits after that point up to `HEAD`.
-- Use those commits to determine what actually shipped in the new release.
+- Open the continuously maintained draft GitHub Release before creating the release branch. Its categorized entries are the release-note candidates collected since the previous published release.
+- Create `release/vX.Y.Z` from `main`, then polish the draft entries into the final user-facing copy. Combine related pull requests and remove implementation detail rather than reconstructing the release from commit history.
 - Update the user-facing changelog in [src/index.html](src/index.html) under the `#whats-new` section.
 - Update the version string in [src/utils/helpers.ts](src/utils/helpers.ts) so the badge and changelog header display the new version.
-- Keep the release branch and deployed artifact aligned before any tag is created.
+- Update the draft GitHub Release to mirror the final in-app changelog.
+- Merge the release branch into `main`, promote `main` to `production`, and verify the Cloudflare deployment before publishing the draft.
 
 ### How to build the changelog well
 
@@ -76,17 +85,15 @@ npm run sync-db-types  # Sync Supabase types to src/types/database.types.ts
 
 ### Tagging guidance
 
-- Default release tags should point at the `main` merge commit created when the release branch is backmerged into `main`.
-- Do not create the release tag while the release PR is still open unless the user explicitly chooses to tag the release branch artifact instead.
-- If tags are meant to represent what is on `main`, create the tag after the release branch has been backmerged into `main`.
-- If tags are meant to represent the exact commit deployed by Cloudflare Pages, tag the release branch commit that was actually deployed.
-- Do not tag `main` before the backmerge if `main` does not yet contain the final release changelog/version bump.
+- Release tags must point at the exact commit deployed from `production`.
+- Do not create or publish the tag while either the release-preparation PR into `main` or the promotion PR into `production` is still open.
+- Verify the Cloudflare production deployment first, then publish the draft GitHub Release. Its `production` target creates the `vX.Y.Z` tag at the deployed branch head.
 
 ### Creating the GitHub Release
 
-- After the release tag has been pushed, create a GitHub Release from that tag so every shipped version has a published release entry on GitHub.
-- Create the release only once the tag exists, and respect the same constraints as the tagging step: do not publish the release while the release PR is still open unless the user explicitly chose to tag/release the deployed release-branch artifact instead.
-- Point the GitHub Release at the same tag chosen in the tagging step. By default that is the `vX.Y.Z` tag on the `main` backmerge commit; use the release-branch commit only if the user opted to tag the exact deployed artifact.
+- Release Drafter creates and maintains the upcoming GitHub Release as a draft; do not create a second release manually.
+- Publish the existing draft only after `main` has been promoted to `production` and the Cloudflare deployment has been verified.
+- Confirm that the draft targets `production` and that its version tag matches the version in [src/utils/helpers.ts](src/utils/helpers.ts).
 - Title the release to match that version tag (for example, `v1.8.5`).
 - The GitHub Release notes should mirror the in-app changelog from the `#whats-new` section in [src/index.html](src/index.html). Do not use raw PR titles or commit messages.
 - Reformat the changelog entries as a Markdown list under a `## What's New` heading, keeping the same user-facing, product-focused phrasing (bold the feature name, then the benefit):
@@ -98,7 +105,7 @@ npm run sync-db-types  # Sync Supabase types to src/types/database.types.ts
     - **More model choices:** New OpenRouter options are available, including expanded Gemini, Grok, Qwen, DeepSeek, and Inception models.
     ```
 
-- Create the release with `gh release create <tag> --title <tag> --notes "..."`, reusing the changelog copy already written for the in-app `#whats-new` section so the GitHub Release and the in-app changelog stay in sync.
+- Publish the prepared draft with `gh release edit <tag> --draft=false --latest`, after confirming its title, notes, and `production` target.
 
 ## Conventions