78 lines
4.5 KiB
Markdown
78 lines
4.5 KiB
Markdown
# 项目发布策略
|
||
|
||
## 策略优先级
|
||
|
||
按以下顺序确定规则，并在来源冲突时停止说明，不要静默覆盖：
|
||
|
||
1. 用户本次请求中明确给出的目标和授权范围。
|
||
2. 项目 `AGENTS.md`、`CLAUDE.md`、发布文档和可选的 `.release-policy.yaml`。
|
||
3. 构建脚本、包清单、CI 工作流和历史发布使用的实际入口。
|
||
4. 代码托管平台当前的默认分支、保护规则、检查和允许的合并方式。
|
||
5. 本 Skill 的默认值。
|
||
|
||
用户请求若与项目硬规则或平台保护冲突，展示冲突并请求处理方式。不要借用户的一句
|
||
“直接发布”绕过仓库声明的检查或保护。
|
||
|
||
开始流程时记录 base commit，并读取该提交对应的项目策略。本次发布分支对策略文件的
|
||
修改不应改变正在执行的流程；新策略从下一次发布开始生效。
|
||
|
||
项目策略不能授予外部写权限。即使配置声明创建 Forge Release 或删除远端分支，也必须
|
||
由用户本次请求明确授权相应动作。
|
||
|
||
## 可选配置
|
||
|
||
项目反复出现同一种歧义时，用户可以要求创建 `.release-policy.yaml`。从
|
||
`templates/release-policy.template.yaml` 复制后，只保留项目真正需要固定的字段。
|
||
|
||
配置只保存可提交的项目策略：
|
||
|
||
- `schema`：配置结构版本，当前为 `1`。
|
||
- `base_branch`：发布 PR/MR 的目标分支。
|
||
- `branch_pattern`：需要准备仓库修改时使用的版本分支格式，支持无展示前缀的规范
|
||
`{version}`；直接发布不因此创建分支。
|
||
- `version.scheme`：`semver` 或项目已经使用的其他方案。
|
||
- `version.sources`：构建和运行实际读取的权威版本文件；项目明确从 Git tag 派生版本时
|
||
可以省略，不要为了发布新增无消费方的版本文件。
|
||
- `tag_pattern`：release tag 格式，支持无展示前缀的规范 `{version}`。
|
||
- `merge_method`：`squash`、`merge` 或 `rebase`。
|
||
- `forge_release`：项目是否建议在 tag 后创建 Forge Release；它不授予创建权限。
|
||
- `tag_signing`：`off`、`optional` 或 `required`。
|
||
- `delete_remote_branch`：发布完成后是否建议清理远端源分支；它只是计划偏好，不是删除
|
||
权限或自动执行指令，仍需用户在本次请求中明确授权。
|
||
|
||
不要在配置中保存 token、账号、私钥路径、个人工作目录或一次性发布状态。不要加入任意
|
||
shell 命令字段；本地验证继续从项目文档、CI 和构建入口发现。
|
||
|
||
读取配置后校验字段集合、类型和枚举值，遇到未知字段时停止。`branch_pattern` 和
|
||
`tag_pattern` 展开后分别用 Git branch/tag ref 规则校验；不要把配置值拼进 shell 字符串。
|
||
`version.sources` 中每一项必须是仓库相对路径，拒绝绝对路径和 `..`。规范化并解析
|
||
symlink 后，目标必须仍在当前 worktree 内；权威来源通常还应由 Git 跟踪。
|
||
|
||
先按版本方案把用户输入规范化。默认 SemVer 接受 `1.6.0` 或作为用户输入的 `v1.6.0`，
|
||
但内部 `{version}` 固定为 `1.6.0`；版本文件写入规范值，branch/tag pattern 分别负责添加
|
||
展示前缀。自定义版本方案按项目文档定义规范值，不能从 pattern 猜测后重复添加前缀。
|
||
|
||
## 无配置时的发现顺序
|
||
|
||
1. 从 remote HEAD 和平台信息确定默认 base，不能确定时询问。
|
||
2. 从项目文档、CI 和构建入口找版本文件及更新方式。
|
||
3. 仅当发布需要修改仓库内容时，从已有分支和已合并 PR/MR 识别命名与合并方式。
|
||
4. 从稳定 tag 识别前缀、版本方案和更新说明范围；项目由 tag 派生版本时，把实际构建
|
||
入口和 tag 历史共同作为版本来源证据，否则只把 tag 当作交叉验证。
|
||
5. 无项目约定时使用 SemVer 和 `v<version>` annotated tag；需要准备仓库修改时再使用
|
||
`release/v<version>` 和 squash merge。默认不创建 Forge Release，不删除远端分支。
|
||
|
||
## 每次执行的计划快照
|
||
|
||
在第一次写操作前列出以下事实：
|
||
|
||
- base 分支、远端 commit 和 tag 将指向的目标 commit。
|
||
- 当前版本、目标版本、版本来源和升级依据。
|
||
- 更新说明的提交范围、来源和拟发布内容。
|
||
- 是否需要修改仓库内容；需要时再列出 worktree 路径与分支名。
|
||
- PR/MR 托管平台和合并方式。
|
||
- tag 与 Forge Release 计划。
|
||
- 用户授权的最远阶段和清理范围。
|
||
|
||
任何事实在执行中改变时刷新计划。改变会影响已授权的远端写目标时，再次获得确认。
|