Skip to content

Latest commit

 

History

History
157 lines (109 loc) · 6.58 KB

push.md

File metadata and controls

157 lines (109 loc) · 6.58 KB

发版手册(Changesets)

面向维护者。说明如何通过 Changesets 发布 @coding-flow/* 系列包的 patch(小版本)/ minor(中版本)/ major(大版本)。

一、标准流程总览

开发改动
  │
  ├─ ① pnpm changeset            # 记录本次变更(选级别 + 写描述),生成 .changeset/*.md
  │
  ├─ ② git add + commit          # 代码 与 changeset 文件 一起提交
  │
  ├─ ③ push / 合并到 main         # changeset 文件必须进入 main
  │
  └─ ④ 发版
       ├─ 方式 A(推荐):CI 自动 —— push 到 main 后由 GitHub Actions 发版
       └─ 方式 B(手动):pnpm push —— 本地 build + publish,版本号固定由人工维护

关键点:本项目采用固定版本发布——版本号由人工在 package.json 中维护,pnpm push 只做 build + publish,不再执行 changeset version 动态升版本。


二、三种版本级别怎么选

级别 命令选择 版本示例(从 0.1.0) 适用场景
patch 小版本 patch 0.1.0 → 0.1.1 bug 修复、性能优化、文档/重构等,不改变对外 API
minor 中版本 minor 0.1.0 → 0.2.0 新增功能、新增 API,向后兼容
major 大版本 major 0.1.0 → 1.0.0 破坏性变更(删除/改名 API、行为不兼容)

本仓库为 Fixed 模式(config.json 的 fixed: [["@coding-flow/*"]]):11 个 @coding-flow/* 包绑定同一版本号,任一包升级,全部同步升到同一版本。 @flow-example/*(app-pc / app-mobile)在 ignore 列表中,不参与发版。


三、第 ① 步:记录变更 pnpm changeset

pnpm changeset

进入交互向导,依次回答:

  1. 选择本次变更影响的包:空格选中 / 取消,回车确认。Fixed 模式下选任意一个 @coding-flow/* 包即可,发版时全组自动同步。
  2. 哪些包需要 major(大版本)?:需要就选中,否则直接回车跳过。
  3. 哪些包需要 minor(中版本)?:需要就选中,否则直接回车跳过。
  4. 未被选为 major/minor 的包自动按 patch(小版本)处理。
  5. 填写变更描述:这段文字会写进各包的 CHANGELOG.md,请写清楚改了什么。

对应三种级别的操作差异:

目标级别 交互操作
patch 选包 → major 提问直接回车 → minor 提问直接回车 → 写描述
minor 选包 → major 提问直接回车 → minor 提问选中该包 → 写描述
major 选包 → major 提问选中该包 → 写描述

执行后生成类似 .changeset/clever-pandas-dance.md 的文件:

---
"@coding-flow/flow-core": patch
---

修复了 XXX 问题

⚠️ 这个文件必须提交进 git。

非交互方式(TTY 不可用时)

直接在 .changeset/ 下手写一个 .md 文件即可,格式如上。文件名任意(config.json、README.md 除外)。例如全部升 patch:

---
"@coding-flow/flow-core": patch
"@coding-flow/flow-design": patch
"@coding-flow/flow-types": patch
---

首屏分包优化

Fixed 模式下列出组内任意成员即可带动全组,这里多列几个只是便于阅读。


四、第 ② ③ 步:提交并合入 main

# 代码与 changeset 文件一起提交
git add -A
git commit -m "feat(xxx): 你的改动描述"
git push origin <你的分支>

# 通过 PR 合并到 main(changeset 文件随之进入 main)

五、第 ④ 步:发版

方式 A:CI 自动发版(推荐)

配置在 .github/workflows/release.yml:

  1. 任何包含 changeset 的改动 push 到 main 后,CI 自动创建/更新一个 "chore: release packages" PR(内含版本号 bump + CHANGELOG 更新)。
  2. 你审阅并合并该 PR。
  3. 合并后 CI 自动执行 pnpm push(build + publish)发布到 npm。

前提:GitHub 仓库 Settings → Secrets 已配置 NPM_TOKEN。

方式 B:本地手动发版 pnpm push(固定版本)

适合没有 CI token、或需要立即发布的场景。先确认在 main 分支且已拉取最新。

固定版本模式下,版本号完全由人工维护(Fixed 模式要求 11 个 @coding-flow/* 包版本一致),pnpm push = build + changeset publish:

git switch main && git pull origin main

# 预检:确认全组包版本一致,且为本次目标版本(如 0.2.21)
pnpm -r --filter "@coding-flow/*" exec node -p "require('./package.json').name + '@' + require('./package.json').version"

# 固定版本发布:build + publish(不改版本号、不消费 changeset)
pnpm push

# 验证发布结果
npm info @coding-flow/flow-core version

需要调整版本号时,单独提交一次人工改动(把各包 package.json 的 version 与对应 CHANGELOG 段落改成目标值),再执行发布。


六、常用命令速查

命令 用途
pnpm changeset 记录一次变更(交互式选包 + 选级别 + 写描述)
pnpm changeset status 查看当前待发布的变更与目标版本
pnpm version-packages 仅消费 changesets、bump 版本号(不发布,固定版本流程下一般不用)
pnpm push / pnpm release build + publish(固定版本,不改版本号)
npm info @coding-flow/<pkg> version 查询 npm 上已发布的版本

七、注意事项 / FAQ

  • changeset 文件丢了怎么办? 没提交进 git 的 changeset 文件不会被 CI/其他机器看到。务必随代码提交;丢失则重新 pnpm changeset。
  • pnpm push 会改版本号吗? 不会。固定版本发布只执行 build + changeset publish,版本号取 package.json 中的值;npm 上已存在同版本时该包会被跳过(提示 already published)。
  • 想发新版本怎么办? 人工把各包 package.json 的 version 改成目标值(Fixed 模式下 11 个包必须一致)并补 CHANGELOG,提交后再 pnpm push。
  • publish 会不会被 git 状态拦截? baseBranch 为 main,且 .npmrc 已设 git-checks=false,不会被拦。但建议在干净的工作区、main 分支上发布。
  • pnpm push 中途失败怎么办? 失败点通常是 build 或 publish,package.json 不会被改动;修复后直接重跑即可,已发布的包会自动跳过。
  • 预发布(beta/alpha)怎么发? 直接把版本写成 x.y.z-beta.N 后执行 pnpm push。