lanyuanxiaoyao
bc7a7c6e81
- 将 backend/cmd/versionctl 和 backend/pkg/projectversion 迁移至独立 versionctl/ Go 模块 - 新增 bump 子命令支持 major/minor/patch 和指定版本号，含版本倒退防护 - 新增 make version-bump 编排完整升迁流程（bump + sync + check + commit + tag） - 更新所有引用路径：根 Makefile、backend/Makefile、release.yml、.golangci.yml - 新增 versionctl/.golangci.yml（精简配置）和 Makefile（lint/test/coverage） - 根 Makefile lint/test 集成 versionctl 模块 - 同步 openspec specs：新增 version-bump spec，更新 release-pipeline spec
134 lines
5.9 KiB
Markdown
134 lines
5.9 KiB
Markdown
# 发布流水线
|
||
|
||
## Purpose
|
||
|
||
定义 tag 驱动的发布流程、跨平台构建产物要求与 Draft Release 组装规则，确保发布结果可复现且可审阅。
|
||
|
||
## Requirements
|
||
|
||
### Requirement: Tag 驱动发布流水线
|
||
|
||
系统 SHALL 仅在符合 `vX.Y.Z` 格式的 Git tag 上触发发布流水线，普通分支 push SHALL NOT 创建发布。发布流水线 SHALL 使用 `./versionctl` 而非 `./backend/cmd/versionctl` 调用版本管理工具。
|
||
|
||
#### Scenario: 有效发布 tag
|
||
|
||
- **WHEN** 仓库收到 `v1.2.3` tag push
|
||
- **THEN** 发布流水线 SHALL 启动版本校验、构建和 Release 组装步骤
|
||
- **AND** 版本校验步骤 SHALL 使用 `go run ./versionctl print` 和 `go run ./versionctl verify-tag` 获取并验证版本
|
||
|
||
#### Scenario: 普通分支推送
|
||
|
||
- **WHEN** 仓库收到非 tag 的分支 push
|
||
- **THEN** 系统 SHALL NOT 创建 GitHub Release
|
||
|
||
### Requirement: 发布流水线 Go 模块缓存覆盖
|
||
|
||
发布流水线 SHALL 在所有 Go module 的 go.sum 文件存在时正确设置 Go 模块缓存路径，确保新增的 `versionctl` module 依赖也被缓存。
|
||
|
||
#### Scenario: CI 缓存覆盖所有 module
|
||
|
||
- **WHEN** 发布流水线设置 Go 模块缓存
|
||
- **THEN** `cache-dependency-path` SHALL 覆盖 `backend/go.sum` 和 `versionctl/go.sum`
|
||
|
||
### Requirement: 三平台发布构建
|
||
|
||
系统 SHALL 在发布流水线中构建 server 与 desktop 的 Linux、Windows、macOS 三个平台产物。
|
||
|
||
#### Scenario: Linux 发布构建
|
||
|
||
- **WHEN** 发布流水线执行 Linux 构建 job
|
||
- **THEN** 系统 SHALL 在可访问 Go、Bun 和 Linux 桌面构建依赖的 shell 环境中执行 Linux 发布构建
|
||
- **AND** 系统 SHALL 生成 Linux server 发布资产
|
||
- **AND** 系统 SHALL 生成 Linux desktop 发布资产
|
||
|
||
#### Scenario: Windows 发布构建
|
||
|
||
- **WHEN** 发布流水线执行 Windows 构建 job
|
||
- **THEN** 系统 SHALL 在包含 MSYS2 / MINGW64 构建工具且可访问 Go 与 Bun 工具链的 shell 环境中执行 Windows 发布构建
|
||
- **AND** 系统 SHALL 生成 Windows server 发布资产
|
||
- **AND** 系统 SHALL 生成 Windows desktop 发布资产
|
||
|
||
#### Scenario: macOS 发布构建
|
||
|
||
- **WHEN** 发布流水线执行 macOS 构建 job
|
||
- **THEN** 系统 SHALL 在可访问 Go、Bun 和 macOS 打包工具链的 shell 环境中执行 macOS 发布构建
|
||
- **AND** 系统 SHALL 生成 darwin-amd64 server 发布资产
|
||
- **AND** 系统 SHALL 生成 darwin-arm64 server 发布资产
|
||
- **AND** 系统 SHALL 生成 macOS desktop universal 发布资产
|
||
|
||
### Requirement: 三平台发布构建预检
|
||
|
||
系统 SHALL 在正式执行各平台 `make release-assets-*` 前验证对应发布 job 的关键工具链可用性，并在环境不完整时快速失败且输出明确诊断。
|
||
|
||
#### Scenario: Linux 预检通过后开始构建
|
||
|
||
- **WHEN** Linux 发布 job 中的 `go`、`bun` 与 Linux 桌面构建依赖均可用
|
||
- **THEN** 系统 SHALL 输出关键工具的版本信息或解析路径
|
||
- **AND** 系统 SHALL 继续执行 `make release-assets-linux`
|
||
|
||
#### Scenario: Windows 预检通过后开始构建
|
||
|
||
- **WHEN** Windows 发布 job 中的 `go`、`bun` 与 MSYS2 构建工具均可用
|
||
- **THEN** 系统 SHALL 输出关键工具的版本信息或解析路径
|
||
- **AND** 系统 SHALL 继续执行 `make release-assets-windows`
|
||
|
||
#### Scenario: macOS 预检通过后开始构建
|
||
|
||
- **WHEN** macOS 发布 job 中的 `go`、`bun` 与 macOS 打包工具均可用
|
||
- **THEN** 系统 SHALL 输出关键工具的版本信息或解析路径
|
||
- **AND** 系统 SHALL 继续执行 `make release-assets-macos`
|
||
|
||
#### Scenario: 任一平台预检发现工具缺失
|
||
|
||
- **WHEN** 任一平台发布 job 中存在关键工具不可用
|
||
- **THEN** 发布流水线 SHALL 在正式构建前失败
|
||
- **AND** 系统 SHALL 在日志中标识缺失的工具链名称
|
||
|
||
### Requirement: 发布流水线运行时兼容性
|
||
|
||
系统 SHALL 保持与 GitHub-hosted runner 当前受支持的 workflow runtime 约束兼容，避免发布流程依赖已声明弃用的 runtime 或执行约束。
|
||
|
||
#### Scenario: runner runtime 升级前完成兼容更新
|
||
|
||
- **WHEN** GitHub-hosted runner 宣布 workflow runtime 或关键执行约束将从旧版本迁移到新版本
|
||
- **THEN** 发布流水线 SHALL 在旧约束移除前完成兼容性更新
|
||
|
||
#### Scenario: 发布流水线执行时不依赖已弃用 runtime
|
||
|
||
- **WHEN** 发布流水线运行 release workflow
|
||
- **THEN** 关键发布步骤 SHALL NOT 依赖已被 GitHub-hosted runner 标记为待移除的 runtime 或执行约束
|
||
|
||
### Requirement: 版本化发布资产命名
|
||
|
||
系统 SHALL 为 server 与 desktop 的发布资产使用包含统一版本号和目标平台信息的文件名，确保 Release 页面可直接区分产物用途与平台。
|
||
|
||
#### Scenario: server 资产命名
|
||
|
||
- **WHEN** 当前发布版本为 `1.2.3`
|
||
- **THEN** Linux server 发布资产文件名 SHALL 包含 `1.2.3`、`linux` 和 `amd64`
|
||
- **AND** Windows server 发布资产文件名 SHALL 包含 `1.2.3`、`windows` 和 `amd64`
|
||
- **AND** macOS server 发布资产文件名 SHALL 分别包含 `1.2.3`、`darwin`、`amd64` 与 `1.2.3`、`darwin`、`arm64`
|
||
|
||
#### Scenario: desktop 资产命名
|
||
|
||
- **WHEN** 当前发布版本为 `1.2.3`
|
||
- **THEN** Linux desktop 发布资产文件名 SHALL 包含 `1.2.3` 和 `linux`
|
||
- **AND** Windows desktop 发布资产文件名 SHALL 包含 `1.2.3` 和 `windows`
|
||
- **AND** macOS desktop universal 发布资产文件名 SHALL 包含 `1.2.3` 和 `macOS`
|
||
|
||
### Requirement: Draft Release 组装
|
||
|
||
系统 SHALL 将发布流水线产物上传到 GitHub Draft Release，由人工确认后再公开发布。
|
||
|
||
#### Scenario: 发布成功时创建 Draft Release
|
||
|
||
- **WHEN** 版本校验通过且三平台发布资产构建完成
|
||
- **THEN** 系统 SHALL 创建或更新与该 tag 对应的 GitHub Draft Release
|
||
- **AND** 系统 SHALL 上传 server 与 desktop 的全部发布资产
|
||
|
||
#### Scenario: 构建失败时阻止完成发布
|
||
|
||
- **WHEN** 任一平台发布资产构建失败或版本校验失败
|
||
- **THEN** 发布流水线 SHALL 失败
|
||
- **AND** 系统 SHALL NOT 产生可直接公开的成功发布结果
|