release

name	release
description	Prepare and execute a full OTGW-firmware release following the documented release process
disable-model-invocation	true

/release - OTGW-firmware Release Skill

Prepare and execute a complete release of the OTGW-firmware project.

Usage

/release <version>

Example: /release 1.3.2

The version argument is the target release version (without v prefix). The previous version is auto-detected from the latest git tag.

Writing style rules

• Never use em dashes in any output: not in release notes, GitHub release body, Discord messages, commit messages, README updates, or conversation text. Use colons, periods, commas, or parentheses instead.
• All release notes and GitHub release messages MUST be in English (international audience).
• No emojis in release notes unless the existing format uses them (README uses them in headings).

Process

Follow these phases in order. There are only 2 mandatory checkpoints (marked with CHECKPOINT). All other phases proceed automatically unless something unexpected happens.

Phase 0: Prepare - clean state & detect previous release

Start every release by ensuring a clean working state and detecting the baseline.

1. Ensure you are on dev: git checkout dev
2. Commit and push any uncommitted changes:
   • git status - if there are modified or untracked files, stage, commit, and push them
   • git pull - incorporate any remote changes
   • git push origin dev - ensure local and remote are in sync
   • Verify: git status must show nothing to commit, working tree clean
3. Detect the latest GitHub release (this is the authoritative previous release, not a local git tag):

   gh release view --json tagName,name,publishedAt --jq '{tag: .tagName, title: .name, date: .publishedAt}'
   

   Store the tag name (e.g., v1.3.2) and published date for use in later phases.
4. Verify the release tag exists locally: git fetch --tags && git log <prev-tag> --oneline -1
5. List code changes since that release: git log <prev-tag>..HEAD --oneline -- src/ | grep -v "CI: update version.h"
   • If there are no code changes, warn the user and ask whether to proceed. (Conditional stop.)

Phase 1: ADR validation

Check whether any architectural changes since the previous release require new or updated ADRs.

1. Review the code commits from Phase 0 step 5
2. For each significant change: does it affect architecture, NFRs, API contracts, new/replaced dependencies, or build/CI tooling?
3. Check docs/adr/ for existing ADRs that may need their Related section updated
4. If new ADRs are needed, create them now on dev before proceeding

Conditional stop: Only pause for user input if ADRs are actually needed. If no ADRs are required, report that and proceed automatically.

Phase 2: Stabilize dev branch

1. Commit all open/uncommitted changes on dev and push to remote
2. Run the build and filter output:

   mkdir -p .tmp
   python build.py 2>&1 | tee .tmp/build_release.log | tail -10
   echo "Exit: $?"
   

   If exit code != 0: read .tmp/build_release.log for diagnosis, fix, retry. If exit code == 0: proceed — do NOT read the full log.
3. Commit version.h changes from build.py and push to remote.

No checkpoint. If the build succeeds, proceed automatically to Phase 3.

Phase 3: Merge dev to main

1. git checkout main && git pull origin main
2. git merge dev
3. Verify merge succeeded without conflicts

Conditional stop: Only pause if there are merge conflicts. Otherwise proceed.

Phase 4: Gather changes, contributors & generate documentation

On main, run the /update-docs workflow in release mode. This handles all documentation in a single efficient parallel pass — do not duplicate work here.

Invoke update-docs:

/update-docs --release <version>

The update-docs workflow (/.claude/skills/update-docs/SKILL.md) will:

1. Detect all source changes since the previous release tag
2. Update affected manual chapters (EN + NL) in parallel
3. Update API docs (openapi.yaml, MQTT.md, REST README) if API changed
4. Update C4 architecture docs if structural changes occurred
5. Gather contributors from GitHub PRs, Discord #beta-testing, and #devs-esp-firmware
6. Generate RELEASE_NOTES_<version>.md, RELEASE_GITHUB_<version>.md, docs/BREAKING_CHANGES.md, and README What's New
7. Clean up docs folder: archive old release notes, move misplaced files, organize reviews

Discord context for contributor gathering:

• Guild ID: 812969634638725140
• #beta-testing: channel ID 914498730001072149
• #devs-esp-firmware: channel ID 924989767966425158
• Maintainer to exclude: 384411356616720384 (number3nl)
• Username formatting: strip trailing 4-digit suffixes (e.g., fuzzyduck3793 → fuzzyduck), except where removal makes the name ambiguous

The update-docs workflow returns without committing (release mode). All generated files are staged for the CHECKPOINT review.

CHECKPOINT 1: Present the categorized changes, contributor list, AND all generated documentation content to the user for review. Wait for approval before proceeding.

Phase 5: Release execution

Proceed directly after Phase 4 approval. No additional confirmation needed.

1. Commit all outstanding changes on main and push to remote
2. Remove pre-release from version.h: Comment out _VERSION_PRERELEASE so the build produces a clean v<version> without -beta. Verify: grep -n "PRERELEASE" src/OTGW-firmware/version.h
3. Run the release build:

   python build.py 2>&1 | tee .tmp/build_release_final.log | tail -10
   echo "Exit: $?"
   

   Fix any issues. Read .tmp/build_release_final.log only on failure.
4. Commit the release build and push main to remote
5. Create draft GitHub release with tag: Derive a short title (3-6 words) summarizing the release theme. Use format v<version> - <Short Title>. Examples: v1.3.2 - File Explorer Reliability Fix, v1.4.0 - REST API v3 & Prometheus. Command: gh release create v<version> --target main --title "v<version> - <Short Title>" --notes-file RELEASE_GITHUB_<version>.md --draft
6. Upload build artifacts to the draft release: gh release upload v<version> build/*.ino.bin build/*.littlefs.bin --clobber
7. Verify artifacts are attached: gh release view v<version> --json assets --jq '.assets[].name'
8. Publish the release: gh release edit v<version> --draft=false --latest

Phase 6: Post-release, Discord announcement & sync dev

1. Verify release artifacts are attached to the GitHub release
2. Remind user to flash a device and check GET /api/v2/device/info
3. Prepare Discord announcements for both community channels:
   • Dutch in #nederlandse-ondersteuning (channel ID: 815561033036333076)
   • English in #english-support (channel ID: 931267109726593116)
   • Both messages include: version, summary, contributor shoutout, download link

CHECKPOINT 2: Show both Discord messages to the user before sending.

4. Send Discord messages after approval
5. Sync dev branch:
   • git checkout dev && git merge main
   • Bump version.h: increment patch version, uncomment _VERSION_PRERELEASE and set to beta
   • Run autoinc-semver.py to update derived strings
   • Commit: feat: Bump version to v<next>-beta for development
   • Push dev

Phase 7: Post-publication corrections (when release notes need updating after publish)

Sometimes a user asks to correct text in an already-published release. Editing RELEASE_GITHUB_<version>.md in the repo does not update the GitHub release page automatically: the release body is a copy taken at gh release create time and lives on GitHub, not in the repo.

Whenever you update release notes, README, or the GitHub release body after publication, do all three in the same round:

1. Edit the files in the repo (RELEASE_NOTES_<version>.md, README.md, RELEASE_GITHUB_<version>.md) on main.
2. Commit and push to main.
3. Update the live GitHub release body with: gh release edit v<version> --notes-file RELEASE_GITHUB_<version>.md
4. Merge main back into dev so both branches reflect the correction: git checkout dev && git merge main && git push origin dev

Skipping step 3 leaves the repo and the GitHub release page out of sync. Skipping step 4 means the next beta cycle starts from stale release docs.

Important rules

• Never use em dashes in any generated text (release notes, Discord messages, commit messages, README, conversation). Use colons, periods, commas, or parentheses.
• Always push to remote after every commit: keep local and remote in sync throughout the release
• Always create releases as draft first: upload artifacts, verify, then publish. Once published, releases are immutable.
• No CI workflows for releases: builds are done locally via python build.py, artifacts uploaded via gh release upload
• Only 2 mandatory checkpoints: Phase 4 (content review) and Phase 6 (Discord messages). Do not add unnecessary confirmation prompts.
• Conditional stops: only pause for merge conflicts, missing ADRs, build failures, or zero code changes.
• Never force-push: all pushes are normal pushes
• Read docs/process/RELEASE_PROCESS.md at the start of every release for the latest process updates
• All release notes and GitHub release messages MUST be in English: international audience
• No emojis in release notes unless the existing format uses them (README uses them in headings)
• GitHub release body is decoupled from the repo file: editing RELEASE_GITHUB_<version>.md does NOT update the published release page. After any edit, run gh release edit v<version> --notes-file RELEASE_GITHUB_<version>.md to push the change to GitHub, then merge main back into dev so both branches carry the correction.