release

name

release

description

Create and publish a new GitHub release for this repository, then verify that the related GitHub Actions firmware release build starts. Use when the user says "/release", "make a release", "create a GitHub release", "publish a release", "tag a release", "major release", "feature release", "minor release", "patch release", "start the release action", or wants firmware release assets generated by GitHub Actions.

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.

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:

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:

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:

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:

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:

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:

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.

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:

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:

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:

gh release view "$TAG" \
  --json tagName,url,isPrerelease,assets \
  --jq '{tagName, url, isPrerelease, assets: [.assets[].name]}'

Expected release assets:

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:

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