|
| 1 | +--- |
| 2 | +name: release |
| 3 | +description: 本仓发版手册:定版本号、bump、跑 release:check、开 PR、合并后打 tag 触发 CI 发布;含首次发布与失败处理。当用户要求「发版」「发布 npm 包」「bump 版本」「打个 tag」时使用。 |
| 4 | +whenToUse: 需要把 dsh-leader-kit 的新版本发布到 npm,或排查发版失败时。 |
| 5 | +--- |
| 6 | + |
| 7 | +# 发版 |
| 8 | + |
| 9 | +目标:让 `npm publish` 只由 tag 触发,版本号、门禁、tag 三者严格对齐。发布不可回收,任何一步没把握就停下来问用户。 |
| 10 | + |
| 11 | +## 前提 |
| 12 | + |
| 13 | +- 改动在 worktree 里(`npm run worktree:spawn <任务名>`),主 checkout 保持干净。 |
| 14 | +- `gh` 已登录、对 `fengshenx/dsh-leader-kit` 有推 tag 权限;`main` 上的 CI 是绿的。 |
| 15 | +- 仅首次发布需要本机发布:`npm login` 完成、账号已开 2FA。 |
| 16 | + |
| 17 | +## 一、定版本号 |
| 18 | + |
| 19 | +`package.json` 的 `version` 是唯一来源,tag 必须是 `v<version>`。 |
| 20 | + |
| 21 | +| 变化 | 用法 | 例子 | |
| 22 | +|---|---|---| |
| 23 | +| 修复 | patch | 0.1.0 → 0.1.1 | |
| 24 | +| 0.x 期间的新能力或破坏性变化 | minor | 0.1.0 → 0.2.0 | |
| 25 | +| 预发布 | 显式写版本 | 0.2.0-rc.1 | |
| 26 | + |
| 27 | +预发布版本带 `-`:CI 用 `next` dist-tag,GitHub Release 标 prerelease,不会顶掉 `latest`。 |
| 28 | + |
| 29 | +## 二、bump |
| 30 | + |
| 31 | +```bash |
| 32 | +npm version patch|minor|major|x.y.z --no-git-tag-version |
| 33 | +git diff -- package.json package-lock.json |
| 34 | +``` |
| 35 | + |
| 36 | +diff 只能出现在这两个文件的版本行。默认的 `npm version` 会提交并打 tag,而那个 tag 指向 worktree 分支的提交,CI 会因「不在 origin/main 上」拒绝。 |
| 37 | + |
| 38 | +## 三、门禁 |
| 39 | + |
| 40 | +```bash |
| 41 | +npm run release:check |
| 42 | +``` |
| 43 | + |
| 44 | +它就是 `prepublishOnly`,也是 CI 的发布门禁:`check` + `build:client` + `verify:pack`。顺序不能倒,`verify:pack` 依赖已构建的 `lib/client.js`。红了先修,不要绕过。 |
| 45 | + |
| 46 | +## 四、提交与 PR |
| 47 | + |
| 48 | +```bash |
| 49 | +git add -A |
| 50 | +git commit -m "chore(release): <version>" |
| 51 | +git push -u origin feature/<任务名> |
| 52 | +gh pr create --fill |
| 53 | +``` |
| 54 | + |
| 55 | +等 CI 绿、PR 合并。合并与 approve 需用户明确指令。 |
| 56 | + |
| 57 | +## 五、合并后打 tag |
| 58 | + |
| 59 | +```bash |
| 60 | +git checkout main && git pull |
| 61 | +git tag -a v<version> -m "v<version>" |
| 62 | +git push origin v<version> |
| 63 | +``` |
| 64 | + |
| 65 | +tag 必须指向 `main` 上的提交。`publish.yml` 会校验 tag 与 `package.json` 版本一致、且提交在 `origin/main` 上。 |
| 66 | + |
| 67 | +## 六、观察 |
| 68 | + |
| 69 | +```bash |
| 70 | +gh run watch |
| 71 | +gh release view v<version> |
| 72 | +npm view dsh-leader-kit@<version> version |
| 73 | +``` |
| 74 | + |
| 75 | +CI 依次:校验 → `npm ci` → OIDC 发布 → 建 Release。发布步骤幂等:版本已存在就跳过,所以 Release 失败可以直接重跑 workflow。 |
| 76 | + |
| 77 | +## 首次发布(包在 npm 上还不存在) |
| 78 | + |
| 79 | +trusted publisher 要求包已存在,所以首个版本必须绕开 CI;但**登记完必须再发一个未发布过的版本**,否则 OIDC 一次都不会跑: |
| 80 | + |
| 81 | +1. 本机确认 `npm run release:check` 通过。 |
| 82 | +2. `npm login`,然后 `npm publish`(不要带路径参数,否则跳过 `prepublishOnly`)。这一步发出 `package.json` 里的当前版本(如 0.1.0),没有 provenance。 |
| 83 | +3. `npm view dsh-leader-kit version` 确认版本上线。 |
| 84 | +4. npmjs.com → 包 → Settings → Trusted Publisher → GitHub Actions: |
| 85 | + - Organization or user: `fengshenx` |
| 86 | + - Repository: `dsh-leader-kit` |
| 87 | + - Workflow filename: `publish.yml` |
| 88 | + - Allowed actions: `npm publish`(预发布再勾 `npm dist-tag`) |
| 89 | +5. **bump 到一个未发布的版本**(如 0.1.1),按第一到五节走完整流程:PR 合并后从 `main` 打 `v0.1.1` tag。这一步才是首次 OIDC 发布。 |
| 90 | +6. 看 `gh run view` 的发布步骤:必须是 `npm notice Publishing ...`,不能是「已发布,跳过 npm publish」。 |
| 91 | +7. 包设置 → Publishing access → 「Require two-factor authentication and disallow tokens」。 |
| 92 | + |
| 93 | +**为什么不能直接推 `v0.1.0`**:第 2 步已经把它发到 registry,`publish.yml` 的「版本已存在就跳过」守卫会打印「已发布,跳过 npm publish」并 exit 0——workflow 整体绿色,但 OIDC 一次都没跑,trusted publisher 配置 2 天后静默过期,而 CI 读数看不出区别。首发版本天然「已存在」,所以首发之后必须有一个新版本真走一遍 OIDC。 |
| 94 | + |
| 95 | +备选(不想在维护者机器上登录):建 `Read and write (stage only)` granular token,`npm stage publish` 后由维护者 `npm stage approve`(要 OTP);它先注册 `0.0.0-stage` 占位包。同样要在登记 trusted publisher 后发一个新版本验证 OIDC。 |
| 96 | + |
| 97 | +## 失败处理 |
| 98 | + |
| 99 | +- **`tag ... 与 package.json 的 ... 不一致`**:版本没提交或 tag 打错。删本地 tag(`git tag -d`)并从 `main` 重打。 |
| 100 | +- **`tag 指向的提交不在 origin/main 上`**:tag 打在了 worktree 分支上。删除远端 tag(`git push origin :refs/tags/<tag>`)后从 `main` 重打。 |
| 101 | +- **版本已存在**:npm 不允许重发同一版本。确认内容后 `npm deprecate`,再发下一个版本。 |
| 102 | +- **`ENEEDAUTH` / 403**:检查 trusted publisher 的仓库、workflow 文件名、Allowed actions 是否与 `publish.yml` 一致;配置是否已过期。 |
| 103 | +- **Release 建失败**:直接重跑 workflow,发布步骤会跳过已存在版本。 |
| 104 | + |
| 105 | +## 禁止 |
| 106 | + |
| 107 | +- 在主 checkout 改版本或跑发布。 |
| 108 | +- 从分支推 tag、对 `main` force push、删除已发布版本所在的 tag。 |
| 109 | +- `npm publish <tarball>`:不跑 `prepublishOnly`,门禁整段跳过。 |
| 110 | +- 未经用户明确指令合并 PR、改包设置或发版。 |
0 commit comments