Beta Prerelease

/beta-prerelease - OTGW-firmware Beta Prerelease Skill

Publish a single beta build to field testers in Discord #beta-testing. Lightweight, repeatable many times within one minor cycle. Does NOT merge to main, does NOT touch the stable _SEMVER_CORE.

Usage

/beta-prerelease

No arguments. Auto-detects the current _VERSION_PRERELEASE and increments it via bin/bump-prerelease.sh.

Token-efficiency rules (apply throughout all phases)

• P1 Build output: Pipe through tee .tmp/build_beta.log | tail -5. Only read .tmp/build_beta.log if exit code != 0.
• P2 Phase 3 reads: Use targeted grep/sed to extract only the relevant section from each file. Never read README, CHANGELOG, or RELEASE_NOTES in full.
• P3 Phase 3 writes: Edit each file and note "Updated." immediately. Do NOT keep all edited content in context — keep only the filename.
• P4 Known Traps: Summarized as 5 bullets below. Read .github/workflows/beta-prerelease.yml only if a trap is actually hit.
• P5 Phase 8 CI poll: Use gh run watch instead of opening a browser.

When to use

Run when a firmware change under src/OTGW-firmware/** or src/libraries/** is committed and ready for field testing. Do NOT use for docs-only commits or full releases to main (use /release <version> for those).

How this differs from /release

Writing style rules

• Never use em dashes — use colons, periods, commas, or parentheses instead.
• All release text MUST be in English (international audience).
• No emojis in release notes or Discord posts.

Process

Phase 0: Prepare — clean state on otgw-1.x.x

The 1.x maintenance/LTS line lives in its own worktree. Run this skill FROM the wt-otgw-1.x.x worktree. Do NOT git checkout otgw-1.x.x inside the dev tree: the branch is already checked out in the worktree and the checkout will fail.

1. Confirm the branch: git rev-parse --abbrev-ref HEAD must print otgw-1.x.x.
2. Verify clean state: git status must be clean (or only the firmware change about to be bumped). Then git pull origin otgw-1.x.x.
3. Detect the latest prerelease tag:

   git fetch --tags
   PREV_TAG=$(git tag --list 'v*-*.*' --sort=-v:refname | head -1)

4. Detect the latest public stable release (store as LATEST_PUBLIC):

   LATEST_PUBLIC=$(gh release view --json tagName --jq '.tagName' 2>/dev/null \
     || git tag --list 'v[0-9]*.[0-9]*.[0-9]*' --sort=-v:refname | grep -v -- '-' | head -1)

5. Read current prerelease: grep _VERSION_PRERELEASE src/OTGW-firmware/version.h

Phase 1: ADR validation

Skip by default. Only pause if the staged firmware change introduces a new architectural pattern, dependency, or NFR shift. Most beta cycles do not need this gate.

Phase 2: Bump prerelease

bin/bump-prerelease.sh

Prints the transition (e.g. beta.3 -> beta.4). Store the new value as NEW_PRERELEASE. The helper does NOT git-add — you stage in Phase 6.

Assemble the tag: TAG="v${SEMVER_CORE}-${NEW_PRERELEASE}"

Phase 3: Refresh README + CHANGELOG + RELEASE_NOTES (mandatory, P2, P3)

The GitHub Action reads these files at the tagged commit. Stale narrative at the tag = stale release page (Trap 1). Refresh immediately after the bump so NEW_PRERELEASE is known.

Staleness check (P2 — targeted extractions, not full reads):

# 1. Commits since last public release (the change set to account for)
git log --pretty=format:'%h %s' "${LATEST_PUBLIC}..HEAD" -- src/OTGW-firmware/ src/libraries/ docs/

# 2. Existing narrative — CHANGELOG [Unreleased] is the rolling beta log on the
#    1.x line. (The README "What's New in v<stable>" sections are refreshed at
#    STABLE release, not per beta, and there is no RELEASE_NOTES_*-beta file.)
grep -A 35 "## \[Unreleased\]" CHANGELOG.md | head -40

Decision:

• Every commit subject since LATEST_PUBLIC appears under CHANGELOG ## [Unreleased] → pass silently, continue to Phase 4.
• Any commit missing → refresh the CHANGELOG now. Stop and ask only if the gap is ambiguous; otherwise edit in-session.

Authoring rules (P3 — write immediately, keep only filename in context):

1. CHANGELOG.md — append under ## [Unreleased] using Keep-a-Changelog headings (### Added/Changed/Fixed/Removed/Documentation). One bullet per change, with ADR/TASK/PR/GH-issue reference. → note "Updated." This is the only mandatory narrative for a 1.x beta.
2. README.md — leave untouched. The 1.x README's "What's New in v<stable>" sections are refreshed at STABLE release (via /release), not per beta.
3. RELEASE_NOTES_<next-stable>.md (e.g. RELEASE_NOTES_1.7.1.md) — optional during a beta cycle (authored in full at stable release). Update it now only if you keep a running draft. → note "Updated."

Skip the CHANGELOG edit only when this is a re-cut at the same change surface (previous tag hit Trap 2). Note the reason in the commit message.

Phase 4: Build verification (P1)

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

Must exit 0. On failure: read .tmp/build_beta.log for diagnosis, fix, retry. Do NOT push a tag on a broken build.