release

# GitHub Release Create a draft GitHub release from `main`, dispatch the `Build Release` action, and watch it build and verify the complete firmware distribution. The workflow uploads assets while the release is private and publishes it only after every asset has been checked. ## Release Flow ### 1. Check Readiness Use `main` unless the user explicitly asks for a different branch. ```bash git status --short --branch git fetch origin --tags --prune git switch main git pull --ff-only origin main gh auth status ``` Do not create a release from uncommitted or unpushed local changes. If local changes are release-related, commit and push them first. If unrelated changes are present, explain that they block a clean release and ask how to proceed. Check recent releases and tags before choosing the new version: ```bash gh release list --limit 10 git tag --list 'v*' --sort=-v:refname | head -20 ``` ### 2. Choose the Version Use long semantic version tags: `vMAJOR.MINOR.PATCH`. Do not create short release tags such as `v1.0` or `v1.1`. If the user gives a short tag, normalize it to the long form and confirm before publishing: ```text v1.0 -> v1.0.0 v1.1 -> v1.1.0 ``` If the user gives a full tag like `v1.2.3`, use that exact tag. If the user asks for a release type instead of a tag, calculate the next version from the latest stable `vX.Y.Z` tag and confirm the calculated tag before publishing. Ignore pre-release tags such as `v1.2.3-beta.1` when choosing the stable base. Version bump rules: ```text major v1.2.3 -> v2.0.0 feature or minor v1.2.3 -> v1.3.0 patch v1.2.3 -> v1.2.4 ``` If there is no existing stable release, treat the first stable release as `v1.0.0` unless the user asks for a different full tag. ### 3. Prepare Web-Asset Compatibility Before creating the tag, add it to the immutable web bundle's compatibility list. This makes the hosted bridge select the declared bundle for the new firmware instead of falling back to the editor embedded in the device. Set the selected tag before preparing the bundle, for example: ```bash # Stable release: TAG="vX.Y.Z" # Pre-release: TAG="vX.Y.Z-beta.N" ``` ```bash git switch -c "jtenniswood/prepare-web-assets-${TAG#v}" python3 scripts/prepare_release_web_assets.py "$TAG" python3 scripts/build.py www --retain-current-bundle python3 scripts/build.py www --check --retain-current-bundle npm run check:release-preflight git add scripts/build.py docs/public/webserver git commit -m "Prepare web assets for $TAG" git push -u origin HEAD gh pr create --base main --title "Prepare web assets for $TAG" --body "Adds $TAG to the declared immutable web bundle compatibility list." ``` Do this before tagging: the tag must point at the source revision that already declares its compatible web bundle. Have that preparation PR reviewed and merged, then return to `main` and pull the merged revision before creating the release tag. The helper retains `dev`, the five current stable releases, and the latest pre-release only. ### 4. Create the Tag and Draft Release Push that exact release tag so every workflow job can check out one immutable source revision. Then create a draft release for the existing tag. Do not publish the draft manually: the workflow owns that final transition. ```bash git tag -a "$TAG" -m "Release $TAG" origin/main git push origin "$TAG" ``` Stable release: ```bash gh release create "$TAG" \ --verify-tag \ --draft \ --notes "Firmware is being built and verified. This draft will publish automatically when complete." \ --fail-on-no-commits ``` Pre-release: ```bash gh release create "$TAG" \ --verify-tag \ --draft \ --notes "Firmware is being built and verified. This draft will publish automatically when complete." \ --fail-on-no-commits \ --prerelease \ --latest=false ``` If a draft already exists, reuse it only after confirming it is still a draft and its tag exists on the remote: ```bash git ls-remote --exit-code --tags origin "refs/tags/$TAG" gh release view "$TAG" --json isDraft,tagName,url ``` Do not close GitHub issues as part of this workflow unless the user explicitly asks; they prefer to test before issues are closed. ### 5. Start and Watch the Release Action Dispatch `Build Release` with the draft tag. Manual dispatch is the only supported release path because a draft release must remain private during the build. ```bash gh workflow run release.yml --ref "$TAG" -f release_tag="$TAG" gh run list \ --workflow release.yml \ --event workflow_dispatch \ --limit 10 \ --json databaseId,status,conclusion,createdAt,headBranch,displayTitle,url ``` Find the newest run for the release tag, then watch it: ```bash gh run watch <run-id> --exit-status ``` If the workflow fails, the release should remain a draft. Report the failed job and do not publish it manually. ### 6. Verify Outputs After `Build Release` succeeds, confirm the release is public and has the expected assets: ```bash gh release view "$TAG" \ --json tagName,url,isDraft,isPrerelease,assets \ --jq '{tagName, url, isDraft, isPrerelease, assets: [.assets[].name]}' ``` Expected release assets: ```text esp32-p4-86.factory.bin esp32-p4-86.manifest.json esp32-p4-86.ota.bin guition-esp32-p4-jc1060p470.factory.bin guition-esp32-p4-jc1060p470.manifest.json guition-esp32-p4-jc1060p470.ota.bin guition-esp32-p4-jc1060p470-v2.factory.bin guition-esp32-p4-jc1060p470-v2.manifest.json guition-esp32-p4-jc1060p470-v2.ota.bin guition-esp32-p4-jc4880p443.factory.bin guition-esp32-p4-jc4880p443.manifest.json guition-esp32-p4-jc4880p443.ota.bin guition-esp32-p4-jc8012p4a1.factory.bin guition-esp32-p4-jc8012p4a1.manifest.json guition-esp32-p4-jc8012p4a1.ota.bin guition-esp32-p4-jc8012p4a1-v2.factory.bin guition-esp32-p4-jc8012p4a1-v2.manifest.json guition-esp32-p4-jc8012p4a1-v2.ota.bin guition-esp32-s3-4848s040.factory.bin guition-esp32-s3-4848s040.manifest.json guition-esp32-s3-4848s040.ota.bin ``` The `Deploy Docs` workflow is configured to run after a successful `Build Release`. Check it if the user asks about docs or firmware download availability: ```bash gh run list --workflow pages.yml --event workflow_run --limit 5 ``` ## Report Back Summarize in plain language: - Release tag and GitHub release URL - `Build Release` run URL and current result - Whether the verified draft was published and release notes were installed - Whether the expected firmware assets are attached - Any docs deployment run URL if checked - Any action needed from the user, especially if a run failed