release
正式发布:候选矩阵 → beta/main 同步 → annotated tag → 稳定 GitHub Release
Try your first task
A source-grounded starter task has not been verified for this skill yet.
SKILL.md
name: releasedescription: 正式发布:候选矩阵 → beta/main 同步 → annotated tag → 稳定 GitHub ReleaseRelease Workflow — 候选矩阵 → main/tag → 正式 Release
你是 UnitySkills 项目的正式发布助手。发布必须遵守以下顺序:
版本一致性检查
→ beta 候选提交完整矩阵
→ 用户确认正式发布
→ beta/main 精确同步
→ 创建并推送 annotated tag
→ tag 自身完整矩阵
→ 创建稳定 GitHub Release
→ 核验 releases/latest 与 Release 跳转地址
→ 重新生成 main 的 Star History 图表
共享规则(/updateversion 引用本节,不另行复述)
- Tag 不可变:已发布的 tag(本地或远端)绝不删除、移动或强制重推;用户靠
#vX.Y.Z安装。版本号一旦创建过 tag 即视为占用(即使尚无 Release),修复须换用新的 patch 版本。 - Star History 豁免:
beta与main是两条平行线,Star History 机器人的图表提交只落main,beta永远不接收,也不为此把main合并或变基进beta。origin/main相对beta只允许多出这些提交,以下两条检查必须均无输出,有输出即停止并列出提交:
发布时git log --format='%h %an %s' beta..origin/main | grep -v -E '^[0-9a-f]+ github-actions\[bot\] docs: update Star History charts$' git diff --name-only beta...origin/main | grep -v -x -E 'docs/star-history-(light|dark)\.svg'main被移动到候选提交,这些图表提交随之丢弃,阶段 10 再重新生成。 releases/latest是更新提醒的唯一来源:Unity 更新提醒只读取它,因此正式 Release 创建成功之前,不能宣称用户已经收到更新通知。查询命令如下;tag_name必须严格为vMAJOR.MINOR.PATCH,且draft、prerelease均为false:gh api 'repos/{owner}/{repo}/releases/latest' \ --jq '{tag_name,html_url,draft,prerelease}'
输入
用户可提供不带 v 的版本号,例如 /release 2.6.0;未提供时从 CHANGELOG.md 顶部最新的 ## [x.y.z] 解析。
- 版本必须严格为
MAJOR.MINOR.PATCH。 - tag 固定为
v{VERSION}。
阶段 1:只读预检查
- 确认当前在
beta分支。 - 工作区必须完全干净:
有任何修改或未跟踪文件都停止,提示先提交或处理。git status --porcelain - 检查 GitHub CLI 登录状态并获取最新远端引用:
任一失败都停止。gh auth status git fetch origin main beta --tags - 将候选提交固定为变量并在整个流程中保持不变:
RELEASE_SHA=$(git rev-parse beta) VERSION_TAG="v{VERSION}" REPO=$(gh repo view --json nameWithOwner --jq .nameWithOwner) - 确认本地
beta没有遗漏远端提交,并通过共享规则 2 的 Star History 豁免检查:
有输出即停止并列出提交;再执行共享规则 2 的两条检查。git log beta..origin/beta --oneline - 检查本地
main是否存在未推送提交。后续会把本地main精确移动到候选提交;若存在必须先交给用户处理:git log origin/main..main --oneline - 验证项目版本锚点、CHANGELOG 顶部版本及 Release tag 格式一致:
python3 .github/scripts/check_project_version.py . \ --expected "{VERSION}" \ --tag "${VERSION_TAG}" - 按共享规则 3 查询当前 GitHub 最新稳定 Release。候选版本必须严格高于它。
- 同时确认本地 tag、远端 tag、GitHub Release 都不存在:
任一已存在都停止(共享规则 1)。git tag -l "${VERSION_TAG}" git ls-remote --tags origin \ "refs/tags/${VERSION_TAG}" \ "refs/tags/${VERSION_TAG}^{}" gh release view "${VERSION_TAG}"
阶段 2:生成并审阅 Release Note
从 CHANGELOG 当前版本条目生成 .releases/v{VERSION}.md。该目录由 .gitignore 忽略。
格式:
# v{VERSION} — {一句话总结,提炼 2-4 个核心特性}
## ⭐ Highlights
- **{特性标题}**:{用户能获得的能力或修复}
## Added
{从 CHANGELOG Added 提炼}
## Changed
{从 CHANGELOG Changed 提炼}
## Fixed
{存在时加入}
## Docs
{存在时加入}
## Compatibility
{涉及 Unity 版本、可选包或破坏性变化时加入}
### 完整更改日志见 https://github.com/{owner}/{repo}/blob/main/CHANGELOG.md
Highlights 使用用户语言,突出“能做什么”,不要照搬内部实现;大量新增 Skill 可用详细版,基础设施更新用精简版。
显示完整 Release Note 给用户审阅。正式发布确认之前可以继续修改该临时文件,但不得修改已固定的 RELEASE_SHA 对应源码;若源码发生变化,必须从阶段 1 重新开始并重新跑矩阵。
阶段 3:推送 beta 并运行预发布完整矩阵
-
将固定候选提交推送到远端
beta,然后验证远端精确一致:git push origin beta git fetch origin beta test "$(git rev-parse origin/beta)" = "${RELEASE_SHA}" -
记录当前最新的 workflow run ID,再从
beta手动触发完整矩阵:BEFORE_RUN_ID=$(gh run list \ --workflow unity-package-compile.yml \ --limit 1 \ --json databaseId \ --jq '.[0].databaseId // 0') gh workflow run unity-package-compile.yml --ref beta -
轮询寻找同时满足以下条件的新运行,并赋值给
PREFLIGHT_RUN_ID:- workflow 为
unity-package-compile.yml - event 为
workflow_dispatch headSha == RELEASE_SHAdatabaseId > BEFORE_RUN_ID
PREFLIGHT_RUN_ID="" for _ in $(seq 1 30); do PREFLIGHT_RUN_ID=$(gh run list \ --workflow unity-package-compile.yml \ --event workflow_dispatch \ --branch beta \ --limit 20 \ --json databaseId,headSha \ --jq "[.[] | select(.headSha == \"${RELEASE_SHA}\" and .databaseId > ${BEFORE_RUN_ID})] | sort_by(.databaseId) | last | .databaseId // empty") test -n "${PREFLIGHT_RUN_ID}" && break sleep 10 done test -n "${PREFLIGHT_RUN_ID}" || { echo "未找到匹配的预发布运行" >&2; false; }找不到、超时或 SHA 不一致时停止,不能误用旧的绿色运行。
- workflow 为
-
等待该运行完成:
gh run watch "${PREFLIGHT_RUN_ID}" --exit-status任一静态检查、Unity 版本或最终汇总失败都停止。修复后生成新提交,并从阶段 1 重新开始。
阶段 4:正式发布确认闸门
在执行任何 main 重写或 tag 创建前,向用户展示:
{VERSION}与RELEASE_SHA- Release Note 文件和完整内容
- 预发布矩阵的成功 URL
origin/main将从哪个 SHA 精确移动到哪个 SHA,以及随之丢弃的 Star History 图表提交数- 接下来会创建不可复用的
v{VERSION}tag 并在检查成功后创建正式 GitHub Release
必须获得用户明确的“确认正式发布”后才能继续。普通的“看看”“准备一下”“生成说明”不构成授权。
阶段 5:安全同步 beta → main
用户确认可能跨越一个对话回合,不能假设之前的 shell 变量或远端状态仍然有效。继续前重新建立并核验固定值:
RELEASE_SHA="{阶段 4 展示并获确认的完整 SHA}"
VERSION_TAG="v{VERSION}"
PREFLIGHT_RUN_ID="{阶段 4 展示的预发布矩阵 run ID}"
git fetch origin main beta --tags
test -z "$(git status --porcelain)"
test "$(git branch --show-current)" = "beta"
test "$(git rev-parse beta)" = "${RELEASE_SHA}"
test "$(git rev-parse origin/beta)" = "${RELEASE_SHA}"
test -z "$(git tag -l "${VERSION_TAG}")"
test -z "$(git ls-remote --tags origin "refs/tags/${VERSION_TAG}" "refs/tags/${VERSION_TAG}^{}")"
再次执行共享规则 2 的两条检查(必须无输出),并通过 gh run view "${PREFLIGHT_RUN_ID}" --json headSha,conclusion 再次确认预发布矩阵仍是同一 RELEASE_SHA 且结论为 success。任一条件变化都使之前的确认失效,回到阶段 1 重新审计。
不使用裸 --force,使用已 fetch 的 main SHA 作为租约,防止检查后远端 main 被其他人更新:
MAIN_REMOTE_BEFORE=$(git rev-parse origin/main)
git push \
--force-with-lease=main:"${MAIN_REMOTE_BEFORE}" \
origin "${RELEASE_SHA}:refs/heads/main"
git fetch origin main beta
git update-ref refs/heads/main "${RELEASE_SHA}"
随后四者必须完全相同:
git rev-parse main beta origin/main origin/beta
并再次确认当前 HEAD 仍在 beta、工作区干净。租约失败意味着远端 main 在确认后发生变化,必须停止并重新审计,不能升级为裸 --force。
阶段 6:创建并验证 annotated tag
tag 必须显式打在已验证的 RELEASE_SHA 上,不能依赖 gh release create --target:
git tag -a "${VERSION_TAG}" "${RELEASE_SHA}" -m "${VERSION_TAG}"
git push origin "refs/tags/${VERSION_TAG}"
本地验证:
test "$(git rev-parse "${VERSION_TAG}^{}")" = "${RELEASE_SHA}"
git merge-base --is-ancestor "${VERSION_TAG}^{}" origin/main
远端验证必须展开 annotated tag,不能只比较 tag 对象 SHA:
TAG_OBJECT=$(gh api \
"repos/{owner}/{repo}/git/ref/tags/${VERSION_TAG}" \
--jq '.object.sha')
TAG_TYPE=$(gh api \
"repos/{owner}/{repo}/git/ref/tags/${VERSION_TAG}" \
--jq '.object.type')
test "${TAG_TYPE}" = "tag"
TAG_COMMIT=$(gh api \
"repos/{owner}/{repo}/git/tags/${TAG_OBJECT}" \
--jq '.object.sha')
test "${TAG_COMMIT}" = "${RELEASE_SHA}"
若本地 tag 已创建但 push 因网络错误失败,只有在远端仍不存在同名 tag、且本地 v{VERSION}^{} 精确等于 RELEASE_SHA 时,才可重试同一条 push;不得重建或移动它。
阶段 7:等待 tag 自身的完整矩阵
推送 tag 会自动触发 Unity Package Compile Matrix。轮询并锁定(同阶段 3 步骤 3 的有界轮询写法,超时停止):
- workflow 为
unity-package-compile.yml - event 为
push headBranch == v{VERSION}headSha == RELEASE_SHA
TAG_RUN_ID=""
for _ in $(seq 1 30); do
TAG_RUN_ID=$(gh run list \
--workflow unity-package-compile.yml \
--event push \
--branch "${VERSION_TAG}" \
--limit 20 \
--json databaseId,headSha \
--jq "[.[] | select(.headSha == \"${RELEASE_SHA}\")] | sort_by(.databaseId) | last | .databaseId // empty")
test -n "${TAG_RUN_ID}" && break
sleep 10
done
test -n "${TAG_RUN_ID}" || { echo "未找到 tag 触发的运行" >&2; false; }
然后执行:
gh run watch "${TAG_RUN_ID}" --exit-status
- 成功后才能创建 GitHub Release。
- 网络、runner 或许可证等瞬时基础设施问题,可在确认源码无误后 rerun 同一个 tag run。
- 如果是源码或测试真实失败,停止发布(共享规则 1);修复后使用新的 patch 版本重新走完整流程。
阶段 8:创建正式稳定 GitHub Release
tag 矩阵成功后,使用已经存在且已验证的 tag 创建 Release:
gh release create "${VERSION_TAG}" \
--verify-tag \
--latest \
--title "${VERSION_TAG}" \
--notes-file ".releases/${VERSION_TAG}.md"
不得使用 --prerelease 或 --draft。不得传 --target,因为 tag 已显式创建并验证。
若命令因网络中断返回不确定结果,先执行 gh release view "${VERSION_TAG}" 判断 Release 是否已经创建,再决定是否重试,不得盲目重复发布操作。
阶段 9:核验更新提醒真实数据源
GitHub API 可能有短暂传播延迟;在有限时间内轮询共享规则 3 的 releases/latest 查询。
最终必须同时满足:
tag_name == v{VERSION}draft == falseprerelease == falsehtml_url == https://github.com/${REPO}/releases/tag/v{VERSION}(REPO须重新取值:gh repo view --json nameWithOwner --jq .nameWithOwner)- 远端 tag 展开后的 commit 等于
RELEASE_SHA main、beta、origin/main、origin/beta均等于RELEASE_SHA- tag 触发的完整矩阵结论为
success
只有全部满足后,才能报告:Unity 的稳定版更新提醒现在会把旧版本用户引导到这个 Release 页面。客户端对成功结果有缓存,因此已打开的 Unity 不保证立刻刷新。
阶段 10:重新生成 main 的 Star History 图表
阶段 9 全部满足后,main 上的图表已随移动退回候选提交里的旧版本。触发一次图表工作流,让 main 立即恢复最新图表(只提交到 main):
gh workflow run update-star-history.yml --ref main
触发失败不影响发布结论,每日定时任务也会补上;在最终输出中注明。
最终输出
输出:
- 正式 Release URL
VERSION_TAG与RELEASE_SHA- 预发布矩阵 URL
- tag 矩阵 URL
- main/beta/远端四方一致性结果
releases/latest核验结果- Star History 图表工作流的触发结果
- 当前分支与工作区状态
不可违反的规则
- 未得到明确正式发布确认,不修改 main、不创建 tag、不创建 Release。
- 遵守共享规则 1–3。
- 不跳过候选提交矩阵,也不拿旧 run 或不同 SHA 的绿色结果代替。
- 不在 tag 矩阵失败时先发布 Release。
- 不把 tag 页面当作更新横幅目标;目标必须是
/releases/tag/v{VERSION}的正式 Release 页面。