release

# GitHub Release Create a GitHub release from `main` and confirm the `Build Release` action starts. In this repo, publishing a release is the normal way to start the firmware build because `.github/workflows/release.yml` uploads firmware assets only for the `release` event. ## 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. Create the Release Use a published release, not a draft, so GitHub emits the `release.published` event and starts the firmware build. Stable release: ```bash TAG="vX.Y.Z" gh release create "$TAG" \ --target main \ --notes "Detailed changelog will be added automatically by the Build Release workflow." \ --fail-on-no-commits ``` Pre-release: ```bash TAG="vX.Y.Z-beta.N" gh release create "$TAG" \ --target main \ --notes "Detailed changelog will be added automatically by the Build Release workflow." \ --fail-on-no-commits \ --prerelease \ --latest=false ``` If a draft release already exists for the tag and the user wants to publish it, publish the draft instead of creating a duplicate: ```bash gh release edit "$TAG" --draft=false ``` Do not close GitHub issues as part of this workflow unless the user explicitly asks; they prefer to test before issues are closed. ### 4. Verify the Release Action Started The related action is `Build Release` in `.github/workflows/release.yml`. Publishing the release should start it automatically. ```bash gh run list \ --workflow release.yml \ --event release \ --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 no `release` event run appears after a short wait, do not silently switch to manual dispatch. Report that the release was created but the automatic action was not found. Manual dispatch is only a test-build fallback: ```bash gh workflow run release.yml --ref "$TAG" ``` Warn the user before using this fallback because workflow-dispatched runs produce an artifact but do not upload firmware files to the GitHub release. ### 5. Verify Outputs After `Build Release` succeeds, confirm the release has the expected assets: ```bash gh release view "$TAG" \ --json tagName,url,isPrerelease,assets \ --jq '{tagName, url, isPrerelease, assets: [.assets[].name]}' ``` Expected release assets: ```text media-player-4848s040.factory.bin media-player-4848s040.manifest.json media-player-4848s040.ota.bin media-player-jc1060p470.factory.bin media-player-jc1060p470.manifest.json media-player-jc1060p470.ota.bin media-player-jc4880p443.factory.bin media-player-jc4880p443.manifest.json media-player-jc4880p443.ota.bin media-player-jc8012p4a1.factory.bin media-player-jc8012p4a1.manifest.json media-player-jc8012p4a1.ota.bin media-player-p4-86-panel.factory.bin media-player-p4-86-panel.manifest.json media-player-p4-86-panel.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 automatic release notes update job ran - 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