generate-release-cx

name	generate-release-cx
description	Create a new release, bump version up to the .10 patch threshold, update changelog, and manage Pull Requests

Generate Release Workflow

Bump version, finalize CHANGELOG, commit, open a PR to main and wait for user confirmation before tagging, publishing, and deploying.

Codex Execution Notes

• Treat // turbo / // turbo-all as instructions to use multi_tool_use.parallel for independent reads, checks, and GitHub calls.
• When the workflow says notify_user or BlockedOnUser: true, present the report/status in the final response and stop. Do not continue into the next phase until the user explicitly approves.

VERSION RULE: Always use PATCH bumps (3.x.y → 3.x.y+1) NEVER use npm version minor or npm version major. Always use: npm version patch --no-git-tag-version The threshold rule: when y reaches 10, bump to 3.(x+1).0 — e.g. 3.8.10 → 3.9.0.

🔴 SINGLE BRANCH RULE: The release/vX.Y.Z branch is the ONLY development branch for the entire release cycle. ALL work — bug fixes, feature implementations, PR integrations, issue resolutions — MUST be committed directly on this branch. Never create separate fix/, feat/, or topic branches. When running /resolve-issues, /implement-features, or /review-prs, always work on the current release branch.

---

⚠️ Two-Phase Flow

Phase 1 (automated): bump → docs → i18n → commit → push → open PR
  ↕  🛑 STOP: Notify user, wait for PR confirmation
Phase 2 (post-merge): tag → publish → GitHub release → Docker → deploy

NEVER push directly to main or create tags before the user confirms the PR.

---

Phase 0: Security Verification (MANDATORY)

Before creating the release, you must ensure the codebase and supply chain are secure and free of known vulnerabilities.

1. Run Local Dependencies Audit:

   npm audit
   

   Fix any high or critical vulnerabilities identified.

2. Check GitHub CodeQL & Dependabot Alerts: Navigate to the repository's Security tab on GitHub, or use the project's vulnerability-scanner skill to analyze active alerts. Ensure all static analysis findings (e.g., prototype pollution, insecure randomness, ReDoS, shell injections) are addressed and logically committed on a target branch.

---

Phase 1: Pre-Merge

1. Create release branch

git checkout -b release/v3.x.y

2. Determine and sync version

Check current version in package.json:

grep '"version"' package.json

🔴 BRANCH-VERSION PARITY RULE: The logical version in package.json MUST exactly match the release branch name. For example, if you are on release/v3.7.0, the version in package.json MUST be 3.7.0.

• If this is the FIRST time generating a release for a new minor/major branch (e.g., bumping from 3.6.9 to 3.7.0), you MUST ensure the version is bumped to match the new branch logic.
• If you are just bumping a patch on the current branch (e.g., 3.6.9 to 3.6.10), use: npm version patch --no-git-tag-version

⚠️ ATOMIC COMMIT RULE — Version bump MUST happen before committing feature files.

CORRECT order:

1. npm version patch --no-git-tag-version ← bump first
2. implement features / fix bugs
3. git add -A && git commit -m "chore(release): v3.x.y — all changes in ONE commit"

OR if features are already staged:

1. implement features (do NOT commit yet)
2. npm version patch --no-git-tag-version ← bump before committing
3. git add -A && git commit -m "chore(release): v3.x.y — all changes in ONE commit"

NEVER do this (creates version mismatch in git history):

• commit features → then bump version → commit package.json separately

This ensures that git show v3.x.y always contains both code changes and the version bump together. The GitHub release tag will point to a commit that includes ALL changes for that version.

3. Regenerate lock file (REQUIRED after version bump)

Mandatory — skipping causes @swc/helpers lock mismatch and CI failures:

npm install

4. Finalize CHANGELOG.md

🔴 NO MIXUPS RULE: Ensure you do NOT mix the backlog of the previous version with the new one. The new version section must ONLY contain the features and fixes for the current release.

Replace the [Unreleased] header with the new version and date. Keep an empty ## [Unreleased] section above it, separated by a horizontal rule (---).

## [Unreleased]

---

## [3.7.0] — 2026-04-19

### ✨ New Features

- ...

### 🐛 Bug Fixes

- ...

---

## [3.6.9] — 2026-04-19

5. Update openapi.yaml version ⚠️ MANDATORY

CI will fail if docs/reference/openapi.yaml version ≠ package.json version (check:docs-sync enforces this).

// turbo

VERSION=$(node -p "require('./package.json').version")
sed -i "s/  version: .*/  version: $VERSION/" docs/reference/openapi.yaml
echo "✓ openapi.yaml → $VERSION"

for dir in electron open-sse; do
  if [ -d "$dir" ] && [ -f "$dir/package.json" ]; then
    (cd "$dir" && npm version "$VERSION" --no-git-tag-version --allow-same-version > /dev/null)
    echo "✓ $dir/package.json → $VERSION"
  fi
done
# Re-run install to assert the workspace lockfile is updated
npm install

6. Update README.md and i18n docs

Manually perform these documentation updates (there is no /update-docs workflow — it was deprecated in v3.8):

• Update feature table rows and "What's new in vX.Y.Z" section in README.md
• Sync feature changes to all 40 language docs/i18n/*/README.md files (use the same row edits across each translated README)
• Update the relevant docs/<AREA>.md if architecture or counts changed
• Re-run npm run check:docs-sync and npm run check:docs-all to catch drift

7. Run tests

// turbo

npm test

All tests must pass before creating the PR.

8. Stage, commit, and push

// turbo-all

git add -A
git commit -m "chore(release): v3.x.y — summary of changes"
git push origin release/v3.x.y

9. Open PR to main

9. Open PR to main

// turbo

VERSION=$(node -p "require('./package.json').version")

# Extract the exact changelog entry for this version from the root CHANGELOG.md
awk "/^## \\[$VERSION\\]/{flag=1; print; next} /^---/{if(flag) {flag=0; exit}} flag" CHANGELOG.md > /tmp/changelog_body.txt

# Append test status and next steps
echo "" >> /tmp/changelog_body.txt
echo "### Tests" >> /tmp/changelog_body.txt
echo "- All tests pass" >> /tmp/changelog_body.txt
echo "" >> /tmp/changelog_body.txt
echo "### ⚠️ After merging: run Phase 2 steps to tag, publish, and deploy." >> /tmp/changelog_body.txt

gh pr create \
  --repo diegosouzapw/OmniRoute \
  --base main \
  --head release/v$VERSION \
  --title "Release v$VERSION" \
  --body-file /tmp/changelog_body.txt

10. 🛑 STOP — Notify User & Await PR Confirmation

This is a mandatory stop point. Present the report in the final response and stop. Do not continue to the next phase until the user explicitly approves.

Inform the user:

• PR URL
• Summary of changes
• Test results
• List of files changed

DO NOT proceed to Phase 2 until the user confirms the PR looks good and merges it.

---

Phase 2: Post-Merge Validation (Local VPS)

Run these steps only AFTER the user has merged the PR into main and all CI jobs have passed.

11. Deploy to Local VPS for Final Validation (MANDATORY)

Before cutting the official git tag and publishing to the world, deploy the main branch to the Local VPS for a final homologation test.

git checkout main
git pull origin main

# Build and pack locally
cd /home/diegosouzapw/dev/proxys/OmniRoute && rm -f omniroute-*.tgz && rm -rf .next/cache app/.next/cache && npm run build:cli && rm -rf app/logs app/coverage app/.git app/.app-build-backup* && npm pack --ignore-scripts

# Deploy to LOCAL VPS (192.168.0.15)
scp omniroute-*.tgz root@192.168.0.15:/tmp/
ssh root@192.168.0.15 "npm install -g /tmp/omniroute-*.tgz --ignore-scripts && cd /usr/lib/node_modules/omniroute/app && npm rebuild better-sqlite3 && pm2 delete omniroute 2>/dev/null; pm2 start /root/.omniroute/ecosystem.config.cjs --update-env && pm2 save && echo '✅ Local done'"

# Verify
curl -s -o /dev/null -w "LOCAL:  HTTP %{http_code}\n" http://192.168.0.15:20128/

12. 🛑 STOP — Notify User & Await Final OK

This is a mandatory stop point. Inform the user that the main branch is now running on the Local VPS. Wait for the user to manually test and give the OK. DO NOT proceed to Phase 3 until the user confirms the local deploy is stable.

---

Phase 3: Official Launch

Run these steps only AFTER the user gives the final OK from the Phase 2 local validation.

13. Create Git Tag and GitHub Release (MANDATORY)

// turbo

git checkout main
git pull origin main
VERSION=$(node -p "require('./package.json').version")

# Extracts the changelog section for this version
NOTES=$(awk "/^## \\[$VERSION\\]/{flag=1; next} /^---/{if(flag) {flag=0; exit}} flag" CHANGELOG.md | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')
if [ -z "$NOTES" ]; then NOTES="OmniRoute v$VERSION Release"; fi

git tag -a "v$VERSION" -m "Release v$VERSION"
git push origin "v$VERSION"
gh release create "v$VERSION" --repo diegosouzapw/OmniRoute --title "v$VERSION" --notes "$NOTES" --target main || gh release edit "v$VERSION" --repo diegosouzapw/OmniRoute --title "v$VERSION" --notes "$NOTES"

14. 🐳 Trigger Docker Hub build (MANDATORY — keep npm and Docker in sync)

CRITICAL: Docker Hub and npm MUST always publish the same version. The Docker image is built automatically via GitHub Actions when a new tag is pushed. After pushing the tag in step 13, verify the workflow runs:

# Verify the Docker workflow triggered
gh run list --repo diegosouzapw/OmniRoute --workflow docker-publish.yml --limit 3

# Wait for the Docker build to complete (usually 5–10 min)
gh run watch --repo diegosouzapw/OmniRoute

15. Publish to NPM (Optional/Automated)

Normally handled by CI, but if manual publish is required:

npm publish

Phase 4: Release Monitoring & Artifact Validation

After triggering the official release, actively monitor the CI pipelines until all artifacts are successfully generated. If any pipeline fails, stop and apply the necessary corrections before continuing.

16. Monitor CI Pipelines

Wait for and verify the successful completion of the following automated jobs:

1. Docker Hub Publish
2. Electron Build
3. NPM Registry Publish (Check with npm info omniroute version)

# Monitor Docker Hub workflow
gh run list --repo diegosouzapw/OmniRoute --workflow docker-publish.yml --limit 1
gh run watch <RUN_ID>

# Monitor Electron build
gh run list --repo diegosouzapw/OmniRoute --workflow electron-release.yml --limit 1
gh run watch <RUN_ID>

# Verify NPM version
npm info omniroute version

17. Handle Failures (If Any)

If a workflow fails:

• Use gh run view <RUN_ID> --log-failed to identify the error.
• Apply the fix on the main branch.
• If necessary, re-trigger the workflow using gh workflow run <workflow_name.yml> --repo diegosouzapw/OmniRoute --ref v3.x.y

18. Preserve release branch

# Branch is kept for historical purposes. Do not delete.

---

Notes

• Ensure CHANGELOG, README and docs/* are current BEFORE this workflow — run npm run check:docs-all and /version-bump first (there is no /update-docs workflow anymore)
• The prepublishOnly script runs npm run build:cli automatically during npm publish
• After npm publish, verify with npm info omniroute version
• Lock file sync errors are caused by skipping npm install after version bump
• Use gh auth switch -u diegosouzapw if git push fails with wrong account

Known CI Pitfalls

CI failure	Cause	Fix
[docs-sync] FAIL - OpenAPI version differs from package.json	Skipped step 5 — docs/reference/openapi.yaml version not updated	Run step 5 (sed -i ...) and commit
[docs-sync] FAIL - CHANGELOG.md first section must be "## [Unreleased]"	## [Unreleased] missing or not at top of CHANGELOG	Add ## [Unreleased]\n\n---\n before the first versioned ## [x.y.z]
Electron Linux .deb build fails (FpmTarget error)	fpm Ruby gem not installed on ubuntu-latest runner	Already fixed in electron-release.yml (gem install fpm step)
Docker Hub 502 error writing layer blob	Transient Docker Hub network error during ARM64 push	Re-run the Docker publish workflow; no code change needed