← LeaderboardThe Skill Leaderboard

release

正式发布:候选矩阵 → beta/main 同步 → annotated tag → 稳定 GitHub Release

Published by Besty0728 ↗Besty0728/Unity-Skills

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 Releaseargument-hint: "[version]"allowed-tools: Bash(git fetch:*), Bash(git status:*), Bash(git branch --show-current:*), Bash(git rev-parse:*), Bash(git log:*), Bash(git diff:*), Bash(git show:*), Bash(git tag -l:*), Bash(git ls-remote:*), Bash(git merge-base:*), Bash(gh run list:*), Bash(gh run view:*), Bash(gh run watch:*), Bash(gh api:*), Bash(gh release view:*), Bash(gh repo view:*), Bash(python3 .github/scripts/check_project_version.py:*), Bash(test:*), Read, Grep, Glob, Edit, Write

Release Workflow — 候选矩阵 → main/tag → 正式 Release

你是 UnitySkills 项目的正式发布助手。发布必须遵守以下顺序:

版本一致性检查
  → beta 候选提交完整矩阵
  → 用户确认正式发布
  → beta/main 精确同步
  → 创建并推送 annotated tag
  → tag 自身完整矩阵
  → 创建稳定 GitHub Release
  → 核验 releases/latest 与 Release 跳转地址
  → 重新生成 main 的 Star History 图表

共享规则(/updateversion 引用本节,不另行复述)

  1. Tag 不可变:已发布的 tag(本地或远端)绝不删除、移动或强制重推;用户靠 #vX.Y.Z 安装。版本号一旦创建过 tag 即视为占用(即使尚无 Release),修复须换用新的 patch 版本。
  2. 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 再重新生成。
  3. 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:只读预检查

  1. 确认当前在 beta 分支。
  2. 工作区必须完全干净:
    git status --porcelain
    
    有任何修改或未跟踪文件都停止,提示先提交或处理。
  3. 检查 GitHub CLI 登录状态并获取最新远端引用:
    gh auth status
    git fetch origin main beta --tags
    
    任一失败都停止。
  4. 将候选提交固定为变量并在整个流程中保持不变:
    RELEASE_SHA=$(git rev-parse beta)
    VERSION_TAG="v{VERSION}"
    REPO=$(gh repo view --json nameWithOwner --jq .nameWithOwner)
    
  5. 确认本地 beta 没有遗漏远端提交,并通过共享规则 2 的 Star History 豁免检查:
    git log beta..origin/beta --oneline
    
    有输出即停止并列出提交;再执行共享规则 2 的两条检查。
  6. 检查本地 main 是否存在未推送提交。后续会把本地 main 精确移动到候选提交;若存在必须先交给用户处理:
    git log origin/main..main --oneline
    
  7. 验证项目版本锚点、CHANGELOG 顶部版本及 Release tag 格式一致:
    python3 .github/scripts/check_project_version.py . \
      --expected "{VERSION}" \
      --tag "${VERSION_TAG}"
    
  8. 按共享规则 3 查询当前 GitHub 最新稳定 Release。候选版本必须严格高于它。
  9. 同时确认本地 tag、远端 tag、GitHub Release 都不存在:
    git tag -l "${VERSION_TAG}"
    git ls-remote --tags origin \
      "refs/tags/${VERSION_TAG}" \
      "refs/tags/${VERSION_TAG}^{}"
    gh release view "${VERSION_TAG}"
    
    任一已存在都停止(共享规则 1)。

阶段 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 并运行预发布完整矩阵

  1. 将固定候选提交推送到远端 beta,然后验证远端精确一致:

    git push origin beta
    git fetch origin beta
    test "$(git rev-parse origin/beta)" = "${RELEASE_SHA}"
    
  2. 记录当前最新的 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
    
  3. 轮询寻找同时满足以下条件的新运行,并赋值给 PREFLIGHT_RUN_ID:

    • workflow 为 unity-package-compile.yml
    • event 为 workflow_dispatch
    • headSha == RELEASE_SHA
    • databaseId > 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 不一致时停止,不能误用旧的绿色运行。

  4. 等待该运行完成:

    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 == false
  • prerelease == false
  • html_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 页面。
release by Besty0728 · The Skill Leaderboard