ci-pub

ci-pub — 自动化发布预检与发布引擎

操作不变量

• 变更前审批关卡：展示版本候选项后立即停止当前轮次；未经人工明确授权，禁止修改清单、变更日志或 Git 历史记录。
• 自主上传边界：严格将执行范围限制在本地预检审计、清单更新和试运行验证；禁止自主上传软件包、推送标签或发布。
• 历史记录原子性：清单、变更日志和工作流更新必须严格包含在单个发布提交中（或修改 HEAD）；禁止创建脱离发布流程的杂项提交或未锚定的发布标签。

执行协议

阶段 1：发现环境与发布设置

1. 发布策略与 CI 审计：
   • 检查 .github/workflows/ 中是否存在现有的发布工作流（例如 publish.yml、release.yml）。识别已配置的触发机制：由标签驱动的 OIDC（refs/tags/*）、手动分派（workflow_dispatch），或不存在（由终端／命令驱动）。
   • CI 初始化关卡（未配置 CI 时）：如果 .github/workflows/ 中没有发布工作流，说明未检测到自动化 CI，并提议基于 references/workflow-single.yml 或 references/workflow-workspace.yml 初始化一个工作流（与发布操作一并提交）。
   • 阅读仓库发布文档和运行手册（doc/runbooks/*publish*.md、docs/*release*.md、CONTRIBUTING.md），提取项目特定的发布不变量和打包限制。
2. 拓扑结构与成员映射：
   • 单个软件包：根目录中的 pubspec.yaml 不包含 workspace: 指令。
   • Pub 工作区：根目录中的 pubspec.yaml 包含 workspace:（要求 Dart SDK ^3.6.0，且根目录的 publish_to: none）。运行 dart pub workspace list（或 fvm dart pub workspace list）以识别候选成员软件包并映射拓扑依赖顺序。
3. 远程与本地版本基线：
   • 查询 pub.dev API（curl -s https://pub.dev/api/packages/<pkg>）以确定远程当前版本（如果返回 404，则标记为 UNPUBLISHED）。
   • 读取本地清单版本（grep '^version:' <pubspec.yaml>）。
   • 比较远程版本与本地版本，以确定提案基线：未递增（Local == Remote）、工作树中已预先递增（Local > Remote），或初次发布（UNPUBLISHED）。

阶段 2：预检质量关卡

运行格式检查（dart format --output=none --set-exit-if-changed .）、分析器检查（dart analyze --fatal-infos）、变更日志就绪情况检查，以及目标发布范围内的测试套件。如果任何验证失败，报告诊断结果并立即停止。

阶段 3：版本提案与轮次停止关卡

1. 评估目标软件包的变更范围（breaking、feat、fix）。
2. 提交发布提案：
   • 单个软件包：根据远程基线提出建议的 SemVer 候选版本（并视情况提供预发布预览版本）。
   • Pub 工作区：按拓扑顺序展示发布矩阵，列出受影响的软件包、远程当前版本与本地版本、拟议版本以及下游约束级联影响。
   • 新增 CI 工作流：如果用户在阶段 1 选择初始化发布工作流，则将 .github/workflows/publish.yml 纳入拟议变更集。
3. 立即停止当前轮次。在用户选择或批准版本提案之前，禁止修改清单或 Git 历史记录。

第 4 阶段：清单变更、试运行验证与交接

1. 清单与变更日志同步：获得用户批准后，同步目标 pubspec.yaml 清单、各软件包的 CHANGELOG.md 文件，以及种子 .github/workflows/publish.yml（如有请求）中的版本。
2. 原子发布提交：暂存已更新的文件，并修改 HEAD（git commit --amend --no-edit），或创建原子发布提交（git commit -m "chore(release): publish packages [...]"）。
3. 最后验证（试运行）：按拓扑顺序依次执行软件包管理器的发布试运行：
   • 单个软件包：dart pub publish --dry-run
   • Pub 工作区：对每个获批软件包执行 dart pub -C <package_dir> publish --dry-run。
   • 如果出现错误、警告或归档内容泄露，提供准确的故障诊断信息并立即停止。
4. 发布就绪报告与定制交接：
   • 提供试运行确认信息和拓扑发布顺序。
   • 根据第 1 阶段确认的发布设置定制交接说明：
     • 由 CI 驱动（推送标签）：提供与仓库标签模式完全匹配的 Git 标签命令（例如，单个软件包使用 v<version>，工作区使用 <package>-v<version>），指向发布提交 SHA，并提供推送标签的命令。
     • 终端/CMD：按拓扑顺序提供直接发布命令（dart pub publish / dart pub -C <package_dir> publish），并注明 pub.dev CDN 的传播窗口为 120 秒；参见 references/pub-workspace-workflow.md。