Traefik 版本发布准备流程详解/release 技能的分支策略、git-cliff 变更日志生成与 PR 约定【免费下载链接】traefikThe Cloud Native Application Proxy项目地址: https://gitcode.com/GitHub_Trending/tr/traefikTraefik 仓库将版本发布准备Preparing a release沉淀为一个可被 Claude Code 直接调用的技能.claude/skills/release/SKILL.md通过/release new-tag一键完成“判定发布类型 → 预检 → 建分支 → 生成 changelog → 提交推送 → 开 PR”的完整流程。读完本文你将掌握 Traefik 三类发布patch、minor RC1、RC2的分支与上一版本 tag 推导规则、git cliff与 cliff.toml 的分组机制以及发布分支命名、提交信息与 PR 标签的完整约定并了解 PR 合入后 .github/workflows/release.yaml 如何自动构建并发布多平台二进制。1. 技能概览调用方式与发布类型判定该技能以标准 frontmatter 声明name: release、description: Prepare a Traefik release (patch, minor RC1, minor RC2, major RC) — generates changelog, bumps versions, commits, pushes, opens PR并标记user-invocable: true。调用形式为/release new-tag文档给出的示例/release v2.11.51— patch release/release v3.8.0-rc.1— minor RC1从 master 出发/release v3.8.0-rc.2— minor RC2从 v3.8 分支出发/release v4.0.0-rc.1— major RC1从 master 出发1.1 解析 tagStep 1技能的第一步Parse tag and detect release type从NEW_TAG中提取以下变量MAJOR、MINOR、PATCH以及RC_NUM非 RC 时为 0IS_RCtag 包含-rc.时为 trueIS_RC1RC_NUM 1时为 true发布类型与分支、上一 tagPrev tag的对应关系如下表直接继承自文档类型示例分支 (BRANCH)Prev tag 判定方式Patchv2.11.51v{major}.{minor}最后一个v{major}.{minor}.*正式版 tagRC1v3.8.0-rc.1master最后一个v{major}.{minor-1}.0-rc.*或ea.*tagRC2v3.8.0-rc.2v{major}.{minor}v{major}.{minor}.0-rc.{RC_NUM-1}随后设置BRANCH与RELEASE_BRANCHprepare-release-${NEW_TAG}即发布准备分支统一采用prepare-release-tag命名。PREV_TAG的探测命令Patchgit tag --sort-version:refname | grep ^v${MAJOR}\.${MINOR}\. | grep -v ^${NEW_TAG}$ | grep -v \-rc\. | head -1RC1git tag --sort-version:refname | grep -E ^v${MAJOR}\.$(( MINOR - 1 ))\.0-(rc|ea)\. | head -1注意这里同时匹配-rc.与-ea.early accesstag用于兜底上一个 minor 没有 RC 而只有 EA 版的场景。RC2直接构造v${MAJOR}.${MINOR}.0-rc.$(( RC_NUM - 1 ))无需查询。若PREV_TAG为空技能会停下来询问用户“Could not auto-detect previous tag. What is the previous tag?”避免在错误区间上生成 changelog。1.2 cliff.toml 如何决定 CHANGELOG 的结构cliff.toml 是 git-cliff 的配置它决定了第 6 步 changelog 输出的最终形态conventional_commits false、filter_unconventional falseTraefik 不采用 Conventional Commits 规范条目分组完全依赖PR 标签而非提交前缀。commit_parsers先过滤噪音带area/infrastructure标签的 PR、消息以Prepare release开头的提交即上一次发布准备产生的提交避免自我引用、merge commit 全部跳过剩余 PR 按标签分组到四个 sectionPR 标签分组CHANGELOG 中的 sectionarea/documentationDocumentationkind/bug/fixBug fixeskind/enhancementEnhancement其他.*Misc分组值中的!-- 0 --、!-- 1 --等 HTML 注释用于控制 section 的排序最终在 CHANGELOG.md 中呈现为Bug fixes:/Enhancement:/Documentation:/Misc:。extract_areas模板宏会从 PR 标签中提取**[area]**前缀只取area/与platform/前缀的标签去掉area/provider/、area/middleware/前缀后合并输出且排除以documentation结尾的标签。例如 PR 标签为area/middleware、kind/bug/fix时条目会渲染成**[middleware]** Fix panic in retry middleware with Websockets ([#13520]… juliens)——这正是 CHANGELOG.md 中每个条目的实际格式。[git]部分tag_pattern v3\\.7.*限定 changelog 版本头只匹配当前主线 v3.7 系列 tagignore_tags v2\\..*忽略 v2 遗留 tag[remote.github]指定owner traefik、repo traefik并以.git/cliff-cache缓存 PR 远程数据commit_range true启用按 tag 区间查询。也就是说git-cliff 在生成时会访问 GitHub API 拉取 PR 标题、编号与标签这也是 Step 2 要求导出GITHUB_TOKEN的原因。版本头模板渲染为## vX.Y.Z (YYYY-MM-DD)加All Commits对比链接与 CHANGELOG.md 现存条目的格式一致。2. 预检清单Step 2快速失败与清晰报错在动任何文件之前技能按顺序执行 6 项检查fail fast, clear messages当前分支git branch --show-current必须等于BRANCH。否则报错Error: must be on branch ${BRANCH}, currently on current.发布分支不存在git branch --list ${RELEASE_BRANCH}必须为空否则Error: branch ${RELEASE_BRANCH} already exists.与上游同步先git fetch upstream再git rev-list HEAD..upstream/${BRANCH} --count。若计数大于 0Error: branch is N commits behind upstream/${BRANCH}. Run: git pull upstream ${BRANCH}CODENAME发布代号读取 .github/workflows/release.yaml提取CODENAME:后的值若缺失则询问用户当前发布代号。当前仓库中该值为CODENAME: langres位于 workflow 的env:段PR 正文与发布流程都会引用它。GITHUB_TOKEN优先使用已设置的$GITHUB_TOKEN否则执行gh auth token获取并导出供 git-cliff 使用对应 cliff.toml 中[remote.github]的远程查询需求。Fork 远端通过git remote -v与gh api user --jq .login找出 push URL 中包含自己 GitHub 用户名的 remote即自己的 fork若有歧义则询问 “Which remote is your fork?”全部通过后技能打印确认摘要并要求用户输入y继续Release type: Patch | Minor RC1 | Minor RC2 | Major RC1 New tag: ${NEW_TAG} Prev tag: ${PREV_TAG} Branch: ${BRANCH} → ${RELEASE_BRANCH} Codename: ${CODENAME}3. 建分支与 RC1 专属操作Step 3–53.1 创建发布分支git checkout -b ${RELEASE_BRANCH}3.2 RC1 专属升级文档中的版本号仅 RC1 执行。先计算OLD_MINORv${MAJOR}.$(( MINOR - 1 ))与NEW_MINORv${MAJOR}.${MINOR}然后用sed将docs/下所有 git 跟踪文件排除构建产物docs/dist/中的${OLD_MINOR}批量替换为${NEW_MINOR}git ls-files docs/ | grep -v ^docs/dist/ | xargs sed -i s/${OLD_MINOR}/${NEW_MINOR}/g同时更新cmd/traefik/traefik.go——该文件包含带版本号的文档 URL。从源码看cmd/traefik/traefik.go 第 103 行有一条日志引用的https://doc.traefik.io/traefik/v3.7/migrate/v3/…迁移指南链接正是此类“版本绑定字符串”RC1 时需要随主线小版本一起滚动保证新版本二进制提示的用户指向对应大版本的文档。技能随后展示改动文件列表并进入Pause 1a“Review the version bump changes in your editor. (y to commit)”确认后再提交git add $(git ls-files docs/ | grep -v ^docs/dist/) cmd/traefik/traefik.go git commit -m Bump documentation references from ${OLD_MINOR} to ${NEW_MINOR}3.3 RC1 专属更新 CODENAME询问用户 “What is the new codename for ${NEW_MINOR}?”然后修改 .github/workflows/release.yaml 中CODENAME:行的值。经Pause 1b确认后提交git add .github/workflows/release.yaml git commit -m Update release codename to new_codename4. 变更日志git-cliff 生成、排序与入库Step 6–74.1 生成GITHUB_TOKEN${GITHUB_TOKEN} git cliff --config script/release/cliff.toml --tag ${NEW_TAG} ${PREV_TAG}..${BRANCH}区间取PREV_TAG..BRANCH而非两个 tag保证包含主干上尚未打 tag 的最新提交--tag ${NEW_TAG}则让模板以新 tag 渲染版本头。4.2 后处理规则Process changelog output对 git-cliff 的原始输出施加两条规范化规则分节内按字母排序带**[area]**前缀的条目按**[...]**内的标签文本排序无标签的条目按整行文本排序并统一放在带标签条目之后。去掉分节内部的空行分节与分节之间的空行保留。处理后的内容前置插入prepend到 CHANGELOG.md 顶部随后展示新增块的前约 30 行供审阅进入Pause 2“CHANGELOG.md updated. Review in your editor, adjust if needed. (y to commit)”确认后提交git add CHANGELOG.md git commit -m Prepare release ${NEW_TAG}5. 推送与创建 PRStep 8–95.1 推送到 forkPause 3确认“Ready to push branch ${RELEASE_BRANCH} to ${FORK_REMOTE}. (y to push)”后git push ${FORK_REMOTE} ${RELEASE_BRANCH}5.2 向 traefik/traefik 开 PRPause 4确认“Ready to open PR against traefik/traefik:${BRANCH}. (y to open PR)”后执行gh pr create \ --repo traefik/traefik \ --base ${BRANCH} \ --head ${GITHUB_USER}:${RELEASE_BRANCH} \ --title Prepare release ${NEW_TAG} \ --label area/documentation \ --label size/S \ --body $(cat PRBODY ### What does this PR do? Prepare release ${NEW_TAG}. aka ${CODENAME} ### Motivation To create a new release. ### More - [ ] Added/updated tests - [x] Added/updated documentation PRBODY )注意 PR 目标分支是BRANCHpatch/RC2 为维护分支如v2.11RC1 为master标题固定为Prepare release ${NEW_TAG}标签固定area/documentationsize/SPR 正文会附上当前代号如aka langres。仓库中还保留了同构的 PR 模板 .github/PULL_REQUEST_TEMPLATE/release.md内容即“Prepare release v{{.Version}}”格式。执行完毕后技能打印 PR URL整个准备流程结束。6. 发布 PR 合入之后tag 触发的自动化流水线发布准备 PR 合入并打上 tag 后后续全部由 CI 完成。从 .github/workflows/release.yaml 可以看到触发条件为push且 tag 匹配v*.*.*且仅限traefik/traefik仓库本体VERSION取github.ref_name。build-webui复用template-webui.yaml构建仪表盘前端产物webui.tar.gz artifactbuildjob 在 17 个os/arch矩阵linux-amd64/386/arm/arm64/ppc64le/s390x/riscv64、darwin-amd64/arm64、windows-amd64/arm64/386、freebsd-amd64/386、openbsd-amd64/386/riscv64上分别执行go generate通过go run ./internal/release os基于 .goreleaser.yml.tmpl 模板渲染出 goreleaser 配置见 internal/release/release.go按GOOS/GOARCH替换模板占位符并输出临时配置文件路径再用 goreleaser 产出tar.gz/zip与校验和文件以*-binariesartifact 形式保留 1 天。releasejob 下载全部平台产物后合并所有平台校验和到traefik_${VERSION}_checksums.txt打包源码traefik-${VERSION}.src.tar.gz排除.github、dist、.idea等以gh release create … --latestfalse创建 GitHub Release注意--latestfalse只有正式 tag 之外由维护者手动标记 latestRC 不会被误标。最后执行 script/deploy.sh使用 secret 中的 SSH 私钥向traefik/traefik-library-image仓库推送对应版本的官方 Docker 镜像更新提交与 tag。7. 手工替代流程与参考文件当 Claude Code 技能不可用时script/release/README.md 提供了等价的手工流程前置条件为已安装git-cliffcargo install git-cliff或包管理器安装、ghCLI 已认证、当前分支即发布分支且与上游同步。其三类操作与本技能一一对应Patch如 v2.11.51git fetch upstream git checkout v2.11 git pull upstream v2.11 git checkout -b prepare-release-v2.11.51然后export GITHUB_TOKEN$(gh auth token) git cliff --config script/release/cliff.toml --tag v2.11.51 v2.11.50..v2.11前置插入 CHANGELOG.md排序规则同第 4.2 节git commit -m Prepare release v2.11.51后推送PR base 为v2.11。Minor/Major RC1如 v3.8.0-rc.1在master上建prepare-release-v3.8.0-rc.1先sed -i s/v3\.7/v3\.8/g批量替换docs/排除docs/dist/与cmd/traefik/traefik.go并单独提交再更新release.yaml中的 CODENAME最后以上一个 RC tag 为区间生成 changelogPR base 为master。Minor/Major RC2如 v3.8.0-rc.2等价于 patch 流程仅分支为v3.8、PREV_TAG为v3.8.0-rc.1、git-cliff 区间为v3.8.0-rc.1..v3.8且只改 CHANGELOG.md不做文档版本替换、不改 codename。需要留意的适用前提本文描述的流程以当前仓库状态为准——cliff.toml的tag_pattern当前锚定为v3\.7.*主线release.yaml中CODENAME当前为langres文档版本字符串为v3.7切换到下一条主线如 v3.8发布 RC1 时这些值会由维护者随发布节奏同步调整。小结Traefik 的发布准备被收敛为一套强约束的流程prepare-release-tag分支命名、按发布类型精确推导PREV_TAG与目标分支、git-cliff 基于 PR 标签的 changelog 分组与排序规范化、以及固定格式的提交信息与 PR 模板。掌握/release技能的这九个步骤后无论自动还是手工都可以按照 script/release/README.md 与 .claude/skills/release/SKILL.md 对同一 tag 复现出完全一致的发布准备提交。【免费下载链接】traefikThe Cloud Native Application Proxy项目地址: https://gitcode.com/GitHub_Trending/tr/traefik创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考