@qlover/fe-release 4.3.1 → 5.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/README.md +110 -119
  2. package/dist/cli.cjs +2550 -7401
  3. package/dist/cli.js +2597 -7472
  4. package/dist/index.cjs +2534 -5426
  5. package/dist/index.d.ts +1707 -1096
  6. package/dist/index.js +2552 -5474
  7. package/package.json +13 -10
package/README.md CHANGED
@@ -21,21 +21,18 @@
21
21
  ## ✨ 特性
22
22
 
23
23
  - **自动化版本管理**
24
-
25
24
  - 基于 `@changesets/cli` 的可靠版本控制
26
25
  - 根据变更自动进行版本更新
27
26
  - 可配置的版本递增策略
28
27
  - 支持语义化版本（Semantic Versioning）
29
28
 
30
29
  - **灵活的发布工作流**
31
-
32
30
  - 手动发布流程，提供直接控制
33
31
  - 基于 PR 的自动化发布工作流（GitHub）
34
32
  - 可自定义的发布策略
35
33
  - 支持多环境发布（开发、测试、生产）
36
34
 
37
35
  - **GitHub 集成**
38
-
39
36
  - 自动化 PR 创建和管理
40
37
  - 智能 PR 标签系统
41
38
  - 自动生成发布说明
@@ -43,7 +40,6 @@
43
40
  - 支持自动合并和冲突解决
44
41
 
45
42
  - **工作区支持**
46
-
47
43
  - 一流的 monorepo 支持
48
44
  - 多包发布协调
49
45
  - 依赖图感知
@@ -71,37 +67,31 @@ pnpm add @qlover/fe-release -D
71
67
 
72
68
  ## 🏃 快速开始
73
69
 
74
- 1. **基础发布**
70
+ 1. **本地创建发布 PR（预览）**
75
71
 
76
72
  ```bash
77
- # 创建发布 PR
78
- fe-release -P
79
-
80
- # 预览发布（不实际执行）
81
- fe-release --dry-run
73
+ # 从 master 创建发布 PR（dry-run）
74
+ fe-release -d -V -s master --github.push-change-labels
82
75
 
83
- # 指定版本类型发布
84
- fe-release --changelog.increment=major
76
+ # 指定版本递增
77
+ fe-release -i patch -s master
78
+ fe-release -i minor -s master
85
79
  ```
86
80
 
87
- 2. **工作区发布**
81
+ 2. **Monorepo 选择性发布**
88
82
 
89
83
  ```bash
90
- # 发布多个包
91
- fe-release --workspaces.change-labels=pkg1,pkg2 -P
84
+ # 只发布带 changes 标签的包
85
+ fe-release -l "changes:packages/fe-release" -i patch -s master
92
86
 
93
- # 指定发布目录
94
- fe-release --publish-path=packages/core
87
+ # 指定包目录
88
+ fe-release --workspaces.packages-directories packages/fe-release,packages/fe-scripts -i patch
95
89
  ```
96
90
 
97
- 3. **环境发布**
91
+ 3. **仅发布（版本已在 release PR 中更新）**
98
92
 
99
93
  ```bash
100
- # 发布到测试环境
101
- fe-release --env=test -P
102
-
103
- # 发布到生产环境
104
- fe-release --env=prod -P
94
+ fe-release --changesetVersion.skip-changeset --changesetVersion.mode publish
105
95
  ```
106
96
 
107
97
  ## 💻 使用方法
@@ -114,108 +104,132 @@ fe-release [options]
114
104
 
115
105
  #### 核心选项
116
106
 
117
- | 选项 | 描述 | 默认值 |
118
- | --------------------------- | ------------------------ | ------- |
119
- | `-v, --version` | 显示版本号 | - |
120
- | `-d, --dry-run` | 预览模式，不实际执行更改 | `false` |
121
- | `-V, --verbose` | 显示详细日志 | `false` |
122
- | `-p, --publish-path` | 包发布路径 | - |
123
- | `-P, --githubPR.release-PR` | 创建发布 PR | `false` |
124
- | `--env` | 发布环境 | `prod` |
107
+ | 选项 | 描述 | 默认值 |
108
+ | ---------------------------------- | ------------------------ | -------- |
109
+ | `-v, --version` | 显示版本号 | - |
110
+ | `-d, --dry-run` | 预览模式，不实际执行更改 | `false` |
111
+ | `-V, --verbose` | 显示详细日志 | `false` |
112
+ | `-s, --source-branch` | 发布 PR 的目标分支 | `master` |
113
+ | `-i, --changesetVersion.increment` | 版本递增类型 | `patch` |
125
114
 
126
115
  #### 高级选项
127
116
 
128
- | 选项 | 描述 | 默认值 |
129
- | -------------------------------- | ---------------- | ------------------------------- |
130
- | `-b, --branch-name` | 发布分支模板 | `release-${pkgName}-${tagName}` |
131
- | `-s, --source-branch` | 源分支 | `master` |
132
- | `-i, --changelog.increment` | 版本递增类型 | `patch` |
133
- | `--changelog.skip` | 跳过更新日志生成 | `false` |
134
- | `--packages-directories` | 变更包目录 | - |
135
- | `-l, --workspaces.change-labels` | 变更标签 | - |
117
+ | 选项 | 描述 | 默认值 |
118
+ | ------------------------------------------------ | ------------------------------ | ---------------------------------- |
119
+ | `-b, --github.branch-name` | 发布分支名模板 | `release/${repoName}-${releaseId}` |
120
+ | `-l, --workspaces.change-labels` | 变更标签（过滤发布范围） | - |
121
+ | `--workspaces.packages-directories` | 扫描的包目录 | `find-workspaces` |
122
+ | `--github.push-change-labels` | 将 changes 标签附加到发布 PR | `false` |
123
+ | `--github.skip-create-release-pr` | 跳过创建 GitHub PR | `false` |
124
+ | `--changesetVersion.mode` | `version` / `publish` / `both` | `version` |
125
+ | `--changesetVersion.skip-changeset` | 跳过 changeset 文件生成 | `false` |
126
+ | `--changesetVersion.ignore-non-updated-packages` | 恢复仅因依赖而变更的包 | `false` |
136
127
 
137
128
  ## ⚙️ 配置
138
129
 
139
130
  ### 环境变量
140
131
 
141
- | 变量 | 描述 | 默认值 |
142
- | ------------------- | ------------- | ------ |
143
- | `FE_RELEASE` | 启用/禁用发布 | `true` |
144
- | `FE_RELEASE_BRANCH` | 源分支 | - |
145
- | `FE_RELEASE_ENV` | 发布环境 | - |
146
- | `FE_RELEASE_TOKEN` | GitHub Token | - |
132
+ | 变量 | 描述 | 默认值 |
133
+ | ----------------------------------- | ----------------------------------- | -------- |
134
+ | `FE_RELEASE` | 启用/禁用发布 | `true` |
135
+ | `FE_RELEASE_BRANCH` | 当前工作分支（CI 中设为 `master`） | `master` |
136
+ | `FE_RELEASE_ENV` | 发布环境 | - |
137
+ | `GITHUB_TOKEN` / `FE_RELEASE_TOKEN` | GitHub Token | - |
138
+ | `NPM_TOKEN` | npm 发布令牌 | - |
147
139
 
148
140
  ### fe-config.json
149
141
 
150
142
  ```json
151
143
  {
152
144
  "release": {
153
- "publishPath": "",
154
- "autoMergeReleasePR": false,
155
- "autoMergeType": "squash",
156
- "branchName": "release-${pkgName}-${tagName}",
157
- "PRTitle": "[${pkgName} Release] Branch:${branch}, Tag:${tagName}, Env:${env}",
158
- "PRBody": "This PR includes version bump to ${tagName}",
159
- "packagesDirectories": ["packages/*"],
160
- "githubPR": {
161
- "commitArgs": ["--no-verify"],
162
- "pushChangedLabels": true,
163
- "releaseName": "Release ${name} v${version}",
164
- "commitMessage": "chore(tag): ${name} v${version}"
145
+ "changesetVersion": {
146
+ "changesetRoot": ".changeset",
147
+ "ignoreNonUpdatedPackages": false
165
148
  },
166
- "changelog": {
167
- "types": [
168
- { "type": "feat", "section": "#### ✨ Features", "hidden": false },
169
- { "type": "fix", "section": "#### 🐞 Bug Fixes", "hidden": false },
170
- { "type": "chore", "section": "#### 🔧 Chores", "hidden": true },
171
- {
172
- "type": "docs",
173
- "section": "#### 📝 Documentation",
174
- "hidden": false
175
- },
176
- {
177
- "type": "refactor",
178
- "section": "#### ♻️ Refactors",
179
- "hidden": false
180
- },
181
- { "type": "perf", "section": "#### 🚀 Performance", "hidden": false },
182
- { "type": "test", "section": "#### 🚨 Tests", "hidden": true },
183
- { "type": "style", "section": "#### 🎨 Styles", "hidden": true },
184
- { "type": "ci", "section": "#### 🔄 CI", "hidden": true },
185
- { "type": "build", "section": "#### 🚧 Build", "hidden": false },
186
- { "type": "revert", "section": "#### ⏪ Reverts", "hidden": true },
187
- { "type": "release", "section": "#### 🔖 Releases", "hidden": true }
188
- ]
149
+ "github": {
150
+ "label": { "name": "CI-Release" },
151
+ "autoMergeReleasePR": false
189
152
  }
190
153
  }
191
154
  }
192
155
  ```
193
156
 
157
+ 配置项通过 `release.<plugin>.*` 与 CLI 的 `--<plugin>.*` 对应，详见 `src/cli.ts` 与 `src/defaults.ts`。
158
+
194
159
  ## 🔄 工作流程
195
160
 
196
- ### 手动发布流程
161
+ fe-base 采用 **master 单线** 发布：功能合入 `master`，需要发版时打上 `CI-Release`。
162
+
163
+ ### 分支与阶段
197
164
 
198
- ```mermaid
199
- graph LR
200
- A[代码变更] --> B[运行 fe-release]
201
- B --> C[版本更新]
202
- C --> D[生成更新日志]
203
- D --> E[创建 Git 标签]
204
- E --> F[发布到 NPM]
205
- F --> G[创建 GitHub Release]
206
165
  ```
166
+ feature/* ──PR──► master ──fe-release──► release/* ──PR──► master ──► npm
167
+ (+ CI-Release)
168
+ ```
169
+
170
+ | 阶段 | 触发条件 | CI 工作流 | 工具 |
171
+ | -------------- | -------------------------------------------------------------- | ----------------------------------- | ------------------------------------------------- |
172
+ | 1. 功能开发 | PR 目标为 `master` | `general-check.yml` | lint / test / build |
173
+ | 2. 创建发布 PR | 合入 `master` 且带 `CI-Release`（且 head 不是 `release/*`） | `release.yml` → `create-release-pr` | `fe-release`（version 模式，git diff 找包） |
174
+ | 3. 发布 | 发布 PR（`release/* → master`）合并且带 `CI-Release` | `release.yml` → `publish` | `fe-release`（publish 模式，不再 bump 版本） |
175
+
176
+ ### 阶段 1：功能 PR（目标分支 `master`）
177
+
178
+ 1. 从 `master` 拉功能分支，开发并提交（遵循 Conventional Commits）。
179
+ 2. 创建 PR，目标分支为 **`master`**。
180
+ 3. CI 自动执行质量检查（lint / test / build）。
181
+ 4. 可选：在 PR 上添加版本递增标签 `increment:major` / `increment:minor` / `increment:patch`（默认 patch）。
182
+
183
+ ### 阶段 2：创建发布 PR（手动打 `CI-Release` 触发）
184
+
185
+ 功能 PR **合并到 master 之前**，在 PR 上添加 **`CI-Release`** 标签（合并时必须仍保留该标签）：
186
+
187
+ 1. 合并时触发 `release.yml` 的 `create-release-pr` job（`closed` 事件）。
188
+ 2. 检出 `master`，运行 `fe-release`（默认 **`changesetVersion` version 模式**）：
189
+ - 通过 **git diff** 检测变更包
190
+ - 生成 changelog、更新 `CHANGELOG.md`、 bump 版本号
191
+ 3. 推送 `release/<repo>-<id>` 分支，创建指向 **`master`** 的发布 PR（自动带 `CI-Release`）。
192
+
193
+ > 合入 master 时**没有** `CI-Release` 标签 → **不会**自动创建发布 PR。
194
+ > 若已合并但未打标签，可在 Actions 里手动运行 **Release sub packages**（`workflow_dispatch`）。
195
+
196
+ 带 **`CI-Release`** 的功能 PR 在打开期间会跳过 `general-check`。
207
197
 
208
- ### PR 发布流程（GitHub）
198
+ ### 阶段 3：发布（合并发布 PR 到 master）
199
+
200
+ 1. 审核并合并带 `CI-Release` 的**发布 PR**（`release/* → master`）到 **`master`**。
201
+ 2. `release.yml` 的 `publish` job 运行 `fe-release --changesetVersion.mode publish`：
202
+ - **不再**生成 changelog 或 bump 版本（`skip-changeset`）
203
+ - 打 tag、发布 npm、创建 GitHub Release
204
+
205
+ ### 标签说明
206
+
207
+ | 标签 | 来源 | 作用 |
208
+ | ------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------- |
209
+ | `CI-Release` | 手动打在功能 PR 上（触发创建发布 PR）；发布 PR 上由 `fe-release` 自动添加 | 触发 version 流程；跳过 general-check；`release/*` 合入 master 后触发 publish |
210
+ | `increment:*` | 手动添加 | 覆盖 semver 递增策略 |
211
+
212
+ > 发布 PR 统一使用 **`CI-Release`** 一个标签即可，无需再单独创建 `Release` 标签。
213
+
214
+ ### 手动触发发布
215
+
216
+ 在 GitHub Actions 中手动运行 **Release sub packages** 工作流（`workflow_dispatch`），
217
+ 会从当前 `master` 创建发布 PR，无需等待某次功能合并。
218
+
219
+ ### 流程图
209
220
 
210
221
  ```mermaid
211
- graph LR
212
- A[创建 PR] --> B[自动添加标签]
213
- B --> C[创建发布 PR]
214
- C --> D[更新版本和日志]
215
- D --> E[CI 发布]
216
- E --> F[发布和打标签]
222
+ graph TD
223
+ A[feature 分支] -->|PR| B[master]
224
+ B -->|lint test build| B
225
+ B -->|合并且带 CI-Release| C[create-release-pr]
226
+ C -->|fe-release git diff| D[release/* → master PR]
227
+ D -->|自动打 CI-Release| E[审核发布 PR]
228
+ E -->|合并到 master| F[publish → npm + GitHub Release]
217
229
  ```
218
230
 
231
+ 更完整的模块说明见 `src/index.ts` 顶部注释。
232
+
219
233
  ## 🔍 常见问题
220
234
 
221
235
  ### 常见问题
@@ -227,13 +241,11 @@ graph LR
227
241
  ```
228
242
 
229
243
  解决方案：
230
-
231
244
  - 检查 `FE_RELEASE` 环境变量
232
245
  - 确认是否有需要发布的变更
233
246
  - 验证包版本是否需要更新
234
247
 
235
248
  2. **PR 创建失败**
236
-
237
249
  - 验证 GitHub token 权限
238
250
  - 检查仓库访问权限
239
251
  - 确认分支是否存在
@@ -252,24 +264,3 @@ graph LR
252
264
  ```bash
253
265
  fe-release -V
254
266
  ```
255
-
256
- ## 🤝 贡献指南
257
-
258
- 1. Fork 本仓库
259
- 2. 创建特性分支
260
- 3. 提交变更
261
- 4. 推送到分支
262
- 5. 创建 Pull Request
263
-
264
- ## 📄 许可证
265
-
266
- 本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件
267
-
268
- ## 🙏 致谢
269
-
270
- - [@changesets/cli](https://github.com/changesets/changesets) 团队
271
- - 所有项目贡献者
272
-
273
- ---
274
-
275
- 更多信息，请访问我们的[文档](https://qlover.github.io/fe-release)。