From 9f04c0b5f8456b77ac05423be28bd2e1f852a595 Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Sun, 26 Apr 2026 10:36:27 +0800 Subject: [PATCH] =?UTF-8?q?fix(release):=20=E4=BF=AE=E5=A4=8D=E8=AF=AD?= =?UTF-8?q?=E4=B9=89=E5=8C=96=E5=8F=91=E7=89=88=E5=AE=A1=E6=9F=A5=E9=97=AE?= =?UTF-8?q?=E9=A2=98?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 修复 semantic-release 配置，切换到 conventionalcommits preset 并显式声明 breaking、revert、patch 语义 - 更新 auto-tag workflow，补充 preview 成功守卫、PAT 存活性校验、snapshot 说明与 release notes summary 输出 - 更新 AGENTS 与 semantic-release topic 的 tracking/trace，记录当前发版规则、验证结果与恢复点 --- .github/workflows/auto-tag.yml | 67 ++++++++++++++--- .releaserc.json | 10 +++ AGENTS.md | 6 +- .../semantic-release-versioning-tracking.md | 46 +++++++++--- .../semantic-release-versioning-trace.md | 72 +++++++++---------- 5 files changed, 141 insertions(+), 60 deletions(-) diff --git a/.github/workflows/auto-tag.yml b/.github/workflows/auto-tag.yml index 9f56dbd2..d502bd64 100644 --- a/.github/workflows/auto-tag.yml +++ b/.github/workflows/auto-tag.yml @@ -27,13 +27,6 @@ jobs: persist-credentials: false ref: ${{ github.sha }} - - name: Validate release branch - run: | - if [ "${GITHUB_REF}" != "refs/heads/main" ]; then - echo "::error::Semantic Release Version and Tag only supports workflow_dispatch on main." - exit 1 - fi - # preview 始终先运行，用于给当前 SHA 生成待发布版本预览。 - name: Semantic release preview id: semantic_release @@ -41,6 +34,8 @@ jobs: with: dry_run: true ci: false + extra_plugins: | + conventional-changelog-conventionalcommits@9.1.0 env: GITHUB_TOKEN: ${{ github.token }} @@ -52,6 +47,9 @@ jobs: echo "next_tag=${{ steps.semantic_release.outputs.new_release_git_tag }}" - name: Write preview summary + env: + RELEASE_PUBLISHED: ${{ steps.semantic_release.outputs.new_release_published }} + RELEASE_NOTES: ${{ steps.semantic_release.outputs.new_release_notes }} run: | { echo "## Semantic Release Preview" @@ -61,6 +59,15 @@ jobs: echo "- Last tag: \`${{ steps.semantic_release.outputs.last_release_git_tag }}\`" echo "- Next version: \`${{ steps.semantic_release.outputs.new_release_version }}\`" echo "- Next tag: \`${{ steps.semantic_release.outputs.new_release_git_tag }}\`" + echo "- Snapshot semantics: this preview is pinned to dispatch SHA \`${{ github.sha }}\`; commits added to \`main\` after the run starts are not included." + if [ "${RELEASE_PUBLISHED}" = "true" ] && [ -n "${RELEASE_NOTES}" ]; then + echo + echo "
Preview release notes" + echo + printf '%s\n' "${RELEASE_NOTES}" + echo + echo "
" + fi echo echo "If the version looks correct, approve the \`release-approval\` environment to continue." } >> "${GITHUB_STEP_SUMMARY}" @@ -68,6 +75,7 @@ jobs: release: if: > github.ref == 'refs/heads/main' && + needs.preview.result == 'success' && needs.preview.outputs.published == 'true' needs: - preview @@ -85,17 +93,46 @@ jobs: ref: ${{ github.sha }} - name: Validate PAT token + env: + PAT_TOKEN: ${{ secrets.PAT_TOKEN }} + REPO_API_URL: ${{ github.api_url }}/repos/${{ github.repository }} run: | if [ -z "${PAT_TOKEN}" ]; then echo "::error::PAT_TOKEN is required because a tag created with GITHUB_TOKEN will not trigger publish.yml." exit 1 fi - env: - PAT_TOKEN: ${{ secrets.PAT_TOKEN }} + + response_file="$(mktemp)" + status_code="$( + curl -sS -o "${response_file}" -w "%{http_code}" \ + -H "Authorization: Bearer ${PAT_TOKEN}" \ + -H "Accept: application/vnd.github+json" \ + -H "X-GitHub-Api-Version: 2022-11-28" \ + "${REPO_API_URL}" + )" + + case "${status_code}" in + 200) + ;; + 401|403) + echo "::error::PAT_TOKEN is invalid or lacks access to ${GITHUB_REPOSITORY} (HTTP ${status_code})." + cat "${response_file}" + exit 1 + ;; + *) + echo "::error::Failed to validate PAT_TOKEN against ${REPO_API_URL} (HTTP ${status_code})." + cat "${response_file}" + exit 1 + ;; + esac - name: Semantic release id: semantic_release uses: cycjimmy/semantic-release-action@v6 + with: + dry_run: false + extra_plugins: | + conventional-changelog-conventionalcommits@9.1.0 env: GITHUB_TOKEN: ${{ secrets.PAT_TOKEN }} @@ -110,6 +147,9 @@ jobs: echo "next_tag=${{ steps.semantic_release.outputs.new_release_git_tag }}" - name: Write release summary + env: + RELEASE_PUBLISHED: ${{ steps.semantic_release.outputs.new_release_published }} + RELEASE_NOTES: ${{ steps.semantic_release.outputs.new_release_notes }} run: | { echo "## Semantic Release Publish" @@ -122,4 +162,13 @@ jobs: echo "- Last tag: \`${{ steps.semantic_release.outputs.last_release_git_tag }}\`" echo "- Next version: \`${{ steps.semantic_release.outputs.new_release_version }}\`" echo "- Next tag: \`${{ steps.semantic_release.outputs.new_release_git_tag }}\`" + echo "- Snapshot semantics: this publish run still uses dispatch SHA \`${{ github.sha }}\`; commits added to \`main\` after the preview started are excluded." + if [ "${RELEASE_PUBLISHED}" = "true" ] && [ -n "${RELEASE_NOTES}" ]; then + echo + echo "
Published release notes" + echo + printf '%s\n' "${RELEASE_NOTES}" + echo + echo "
" + fi } >> "${GITHUB_STEP_SUMMARY}" diff --git a/.releaserc.json b/.releaserc.json index cf7e1a2c..c5d1ba04 100644 --- a/.releaserc.json +++ b/.releaserc.json @@ -7,7 +7,16 @@ [ "@semantic-release/commit-analyzer", { + "preset": "conventionalcommits", "releaseRules": [ + { + "breaking": true, + "release": "major" + }, + { + "revert": true, + "release": "patch" + }, { "type": "feat", "release": "minor" @@ -60,6 +69,7 @@ [ "@semantic-release/release-notes-generator", { + "preset": "conventionalcommits", "parserOpts": { "noteKeywords": [ "BREAKING CHANGE", diff --git a/AGENTS.md b/AGENTS.md index 1383f5f9..06610a00 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -59,9 +59,11 @@ All AI agents and contributors must follow these rules when writing, reviewing, - Use `feat` only for user-facing or consumer-facing capability additions that should raise the next released version's `minor` segment. - Use `fix` for behavior corrections, `perf` for observable performance improvements, and `refactor` only for - non-feature code restructuring. + non-feature code restructuring; these should raise the next released version's `patch` segment. - Use `docs`、`test`、`chore`、`build`、`ci`、`style` for their literal categories; do not encode these changes as - `feat` just because they feel important. + `feat` just because they feel important. These categories MUST NOT trigger a release. + - Use `BREAKING CHANGE` in the commit footer or `!` after the type / scope header (for example `feat!:` or + `feat(core)!:`) when the change should raise the next released version's `major` segment. - Documentation-only changes MUST NOT use `feat`, including new guides, refreshed examples, navigation updates, and adoption notes for existing capabilities. If a commit changes both product behavior and related docs, either split the commit or use `feat` only when the code/package behavior is the primary released change. diff --git a/ai-plan/public/semantic-release-versioning/todos/semantic-release-versioning-tracking.md b/ai-plan/public/semantic-release-versioning/todos/semantic-release-versioning-tracking.md index 9841fab7..ba8ebb56 100644 --- a/ai-plan/public/semantic-release-versioning/todos/semantic-release-versioning-tracking.md +++ b/ai-plan/public/semantic-release-versioning/todos/semantic-release-versioning-tracking.md @@ -13,18 +13,20 @@ ## 当前恢复点 -- 恢复点编号：`SEMREL-RP-001` -- 当前阶段：`Phase 1` +- 恢复点编号：`SEMREL-RP-002` +- 当前阶段：`Phase 2` - 当前焦点： - - 增加 `.releaserc.json`，仅启用版本分析与 release notes 生成，不启用 GitHub Release 发布插件 - - 将 `auto-tag.yml` 改成同一次 `workflow_dispatch` 里先 `preview`，再等待 environment 审批后继续 `release` - - 明确 `PAT_TOKEN` 与 `GITHUB_TOKEN` 的职责边界，确保 tag 继续触发 `publish.yml` + - 让 `.releaserc.json` 对 `BREAKING CHANGE` 与 `feat!:` / `feat(scope)!:` 的 `major` 语义与文档保持一致 + - 将 `auto-tag.yml` 的 preview / release 输出与 PR review 建议对齐，避免 release notes 被静默丢弃 + - 提前校验 `PAT_TOKEN` 的真实可用性，并把当前 PR review 修复结果同步回 `AGENTS.md` 与 active trace ### 已知风险 - `GITHUB_TOKEN` 推送 tag 不会再触发另一个 workflow，真实发布仍需要 `PAT_TOKEN` - `semantic-release` 的版本判断完全依赖 Conventional Commits；不规范提交会直接影响版本计算 -- 当前仓库本地 `dotnet clean/build` 仍受 WSL fallback NuGet 路径影响，验证时需要继续采用已知可用的直接构建命令 +- `cycjimmy/semantic-release-action@v6` 需要在 preview / release 两端都安装 `conventional-changelog-conventionalcommits` + 以保证 `conventionalcommits` preset 在 GitHub Actions 中可解析 +- 当前仓库本地 `dotnet clean/build` 会带出既有 analyzer warnings；本轮仅修正发版配置与文档，不额外处理这些历史 warning ## 已完成 @@ -34,15 +36,32 @@ - 已确认 `v0.0.222..HEAD` 之间存在 `feat(...)` 提交，按目标规则首次 dry-run 预期版本应为 `v0.1.0` - 已新增 `.releaserc.json`，仅保留 `@semantic-release/commit-analyzer` 与 `@semantic-release/release-notes-generator`，避免 `semantic-release` 直接创建 GitHub Release +- 已将 `.releaserc.json` 的 `commit-analyzer` / `release-notes-generator` 同步切换到 `conventionalcommits` + preset，并显式声明： + - `breaking -> major` + - `revert -> patch` + - `feat -> minor` + - `fix/perf/refactor -> patch` + - `docs/test/chore/build/ci/style -> no release` - 已将 `.github/workflows/auto-tag.yml` 重写为： - `workflow_dispatch` 启动后总是先跑 `preview` - `preview` 只执行 dry-run，输出 `last_tag`、`next_version` 与 `next_tag` - `release` job 依赖 `preview` 输出，并通过 `release-approval` environment 暂停等待人工确认 - 人工批准后，`release` 在同一 SHA 上执行真实打 tag，并把 preview / release 结果都写入 job summary +- 已按 PR review 修复 `auto-tag.yml`： + - 删除 preview job 中与 job 级 `if` 重复的运行时分支校验 + - 为 release job 增加 `needs.preview.result == 'success'` 守卫 + - 为 preview / release 的 semantic-release action 显式安装 `conventional-changelog-conventionalcommits@9.1.0` + - 在 release 前通过 GitHub API 校验 `PAT_TOKEN` 是否真实可访问当前仓库 + - 在 preview / release summary 中补充 snapshot 语义与生成的 release notes - 已明确真实打 tag 仍使用 `PAT_TOKEN`，因为 `GITHUB_TOKEN` 推送的 tag 不会继续触发 `publish.yml` -- 已更新 `AGENTS.md` 的 Conventional Commit 规则，显式禁止把纯文档变更写成 `feat(...)` 或 `feat(docs)` +- 已更新 `AGENTS.md` 的 Conventional Commit 规则，显式补充： + - `fix/perf/refactor -> patch` + - `docs/test/chore/build/ci/style -> no release` + - `BREAKING CHANGE` 或 `!` header -> major - 已移除基于 `workflow_run` 和 `[release ci]` 的自动发版门闸，后续版本预览与真实发版都由维护者手动触发 - 已将 release 流程从“两次独立 workflow_dispatch”收敛为“同一次 run 里 preview + 审批 + release”的链路 +- 已精简 active trace，移除已废弃的 `release_mode=preview|release` 中间方案，保留当前有效恢复点 ## 验证 @@ -64,12 +83,19 @@ - `npx --yes semantic-release --dry-run --no-ci`（在 `/tmp/gframework-semrel-dryrun`） - 结果：通过 - 备注：dry-run 成功识别 `v0.0.222` 为最新 release，并分析 `269` 个提交；按当前规则会提升到下一次 `minor` 发布，预期 tag 为 `v0.1.0` +- `npx --yes -p semantic-release -p conventional-changelog-conventionalcommits@9.1.0 semantic-release --dry-run --no-ci`（在 `/tmp/gframework-semrel-dryrun`） + - 结果：通过 + - 备注：成功加载 `@semantic-release/commit-analyzer` 与 `@semantic-release/release-notes-generator`，证明 + `conventionalcommits` preset 包可被解析；本次 dry-run 未继续出版本，是因为干净克隆的 `main` 已落后远端 - `dotnet build GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj -c Release -p:RestoreFallbackFolders=`（手动发版入口调整后复验） - 结果：通过 - 备注：`0 warning / 0 error` +- `dotnet build GFramework.sln -c Release` + - 结果：通过 + - 备注：Release 构建完成，`639 warning / 0 error`；warning 为仓库既有基线，与本轮 workflow / doc 改动无新增关联项 ## 下一步 -1. 在仓库 Settings -> Environments 中为 `release-approval` 配置 required reviewers，确保 workflow 会在 preview 后真正暂停 -2. 复核 Actions summary 呈现方式是否还需要更醒目的版本展示 -3. 若本轮验证通过，按仓库要求创建补充提交并等待你审阅同次 run 的手动发版流程细节 +1. 复核当前 PR review 的 open threads 是否只剩等待 push 的已修复项 +2. 将本轮修复提交到当前分支，等待 GitHub reviewer 重新评估 +3. 若后续需要，再在真实仓库主线最新快照上复验一次 `semantic-release` dry-run 结果展示 diff --git a/ai-plan/public/semantic-release-versioning/traces/semantic-release-versioning-trace.md b/ai-plan/public/semantic-release-versioning/traces/semantic-release-versioning-trace.md index 63a3851b..5aba262a 100644 --- a/ai-plan/public/semantic-release-versioning/traces/semantic-release-versioning-trace.md +++ b/ai-plan/public/semantic-release-versioning/traces/semantic-release-versioning-trace.md @@ -2,49 +2,43 @@ ## 2026-04-26 -### 阶段：方案落地准备（SEMREL-RP-001） +### 当前恢复点（SEMREL-RP-002） -- 读取当前 `auto-tag.yml` 与 `publish.yml`，确认最小侵入改法应只替换版本判断与打 tag，保留 tag 触发发布链 -- 核对最近 tag 与提交历史： - - 最新 tag 为 `v0.0.222` - - `v0.0.222..HEAD` 含多条 `feat(...)`，按目标规则首次 dry-run 预期结果为 `v0.1.0` -- 补建本主题的 active tracking / trace 入口，并在 `ai-plan/public/README.md` 中为 - `feat/semantic-release-versioning` 建立 worktree 映射 - -### 阶段：配置落地与验证（SEMREL-RP-001） - -- 新增 `.releaserc.json`，显式固定： +- 当前链路： + - `workflow_dispatch` 手动启动 + - `preview` 对 dispatch SHA 执行 dry-run + - `release-approval` environment 审批 + - `release` 在同一次 run、同一 SHA 上执行真实打 tag +- 当前规则： + - `conventionalcommits` preset 负责解析 `feat!:` / `feat(scope)!:` 与 `BREAKING CHANGE` - `feat -> minor` - `fix/perf/refactor -> patch` - `docs/test/chore/build/ci/style -> no release` - - `BREAKING CHANGE` / `BREAKING CHANGES` 作为 major 信号 -- 重写 `auto-tag.yml`： - - 改为纯 `workflow_dispatch` 手动入口 - - 增加 `release_mode=preview|release` 输入 - - `preview` 只跑 dry-run 并输出 `last_tag`、`next_version`、`next_tag` - - `release` 由维护者手动触发真实打 tag，并要求 `PAT_TOKEN` -- 收紧 `AGENTS.md` 的提交信息约束，明确提交类型必须反映 release semantics，纯文档变更禁止写成 `feat(...)` -- 按用户反馈继续调整发版入口： - - 删除基于 `workflow_run` 的自动发版路径 - - 统一改为 `workflow_dispatch` 手动触发 - - 先在同一次 run 中执行 `preview` - - 再通过 `release-approval` environment 做人工确认 - - 审批通过后继续同一 SHA 的真实 `release` -- 复验最小构建命令： - - `dotnet build GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj -c Release -p:RestoreFallbackFolders=` - - 结果：通过，`0 warning / 0 error` -- 完成最小构建验证： - - `dotnet build GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj -c Release -p:RestoreFallbackFolders=` - - 结果：通过，`0 warning / 0 error` -- 直接在当前工作树执行 `semantic-release --dry-run` 时命中本地 tag 抓取冲突： - - `git fetch --tags ... would clobber existing tag` - - 结论：当前工作树不适合作为 dry-run 验证环境 -- 改用干净临时克隆 `/tmp/gframework-semrel-dryrun` 再跑 dry-run： - - 成功识别 `v0.0.222` 为最新 release - - 成功分析 `269` 个提交 - - 按当前规则得出下一次应为 `minor` 发布，预期版本窗口从 `0.0.222` 提升到 `0.1.0` + - `breaking -> major` +- 当前 workflow 加固： + - `release` 额外要求 `needs.preview.result == 'success'` + - `PAT_TOKEN` 在真实 release 前通过 GitHub API 做存活性校验 + - preview / release summary 会展示 snapshot 语义与生成的 release notes + +### 本轮关键决策 + +- 保留 `@semantic-release/release-notes-generator`，但不再让它白跑： + - 继续生成 notes + - 将 notes 写入 GitHub Actions summary +- 不保留已废弃的 `release_mode=preview|release` 中间方案： + - active trace 只保留当前有效链路 + - 历史演进以 tracking 文档的已完成项为准 + +### 验证结论 + +1. `npx --yes -p semantic-release -p conventional-changelog-conventionalcommits@9.1.0 semantic-release --dry-run --no-ci` + - 已确认新 preset 包可加载，`commit-analyzer` 与 `release-notes-generator` 正常初始化 + - 本次 dry-run 未继续出版本，因为干净克隆的 `main` 已落后远端 +2. `dotnet build GFramework.sln -c Release` + - 通过，`639 warning / 0 error` + - warning 为仓库既有基线，本轮未新增关联 warning ### 下一步 -1. 复核变更 diff 并创建提交 -2. 向用户说明新的发版链路与可优化点 +1. 复查当前 PR 的 open review threads 是否只剩等待 push 的已修复项 +2. 创建提交并推送当前分支