ci-pub
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
Chineseci-pub — Automated Release Preflight & Publication Engine
ci-pub — 自动化发布预检与发布引擎
Operating Invariants
操作约束
- Pre-Mutation Gate: Present version candidates and halt turn immediately; forbid modifying manifests, changelogs, or git history without affirmative human authorization.
- Autonomous Upload Boundary: Confine execution strictly to local preflight audit, manifest updates, and dry-run verification; forbid uploading packages, pushing tags, or publishing autonomously.
- Atomic History Integrity: Stage manifest, changelog, and workflow updates strictly within a single release commit (or amend HEAD); forbid detached chore commits or unanchored release tags.
- 变更前门禁:提出版本候选项后立即终止本轮操作;未经人工明确授权,禁止修改清单、变更日志或 Git 历史记录。
- 自主上传边界:执行范围严格限定于本地发布预检审计、清单更新和 dry-run 验证;禁止自主上传包、推送标签或执行发布。
- 原子历史完整性:清单、变更日志和工作流更新必须严格置于同一次发布提交(或 amend HEAD)中;禁止使用独立的 chore 提交或未锚定到提交记录的发布标签。
Execution Protocol
执行协议
Phase 1: Environment & Publishing Setup Discovery
阶段 1:环境与发布设置发现
- Publishing Strategy & CI Audit:
- Inspect for existing release/publish workflows (e.g.
.github/workflows/,publish.yml). Identify configured trigger mechanisms: tag-driven OIDC (release.yml), manual dispatch (refs/tags/*), or absent (terminal/cmd driven).workflow_dispatch - CI Seeding Gate (If No CI Configured): If lacks a publish workflow, highlight that no automated CI was detected and offer to seed one from
.github/workflows/orreferences/workflow-single.yml(to be committed atomically with the release).references/workflow-workspace.yml - Read repository publishing documentation and runbooks (,
doc/runbooks/*publish*.md,docs/*release*.md) to extract project-specific release invariants and packaging constraints.CONTRIBUTING.md
- Inspect
- Topology & Member Mapping:
- Single Package: Root without
pubspec.yamldirective.workspace: - Pub Workspace: Root contains
pubspec.yaml(requires Dart SDKworkspace:, root^3.6.0). Runpublish_to: none(ordart pub workspace list) to identify candidate member packages and map topological dependency order.fvm dart pub workspace list
- Single Package: Root
- Remote & Local Version Baseline:
- Query pub.dev API () to resolve Remote Live Version (or mark
curl -s https://pub.dev/api/packages/<pkg>if 404).UNPUBLISHED - Read Local Manifest Version ().
grep '^version:' <pubspec.yaml> - Compare Remote vs Local to baseline the proposal: unbumped (), pre-bumped in working tree (
Local == Remote), or initial release (Local > Remote).UNPUBLISHED
- Query pub.dev API (
- 发布策略与 CI 审计:
- 检查 中现有的发布或发布工作流(例如
.github/workflows/、publish.yml)。识别已配置的触发机制:标签驱动的 OIDC(release.yml)、手动触发(refs/tags/*),或未配置(由 terminal/cmd 驱动)。workflow_dispatch - CI 配置初始化门禁(未配置 CI 时):如果 中没有发布工作流,应指出未检测到自动化 CI,并提供基于
.github/workflows/或references/workflow-single.yml初始化工作流的选项(需与发布操作一起原子提交)。references/workflow-workspace.yml - 阅读仓库发布文档和操作手册(、
doc/runbooks/*publish*.md、docs/*release*.md),提取项目特定的发布约束和打包限制。CONTRIBUTING.md
- 检查
- 拓扑结构与成员映射:
- 单包:根目录 不包含
pubspec.yaml指令。workspace: - Pub Workspace:根目录 包含
pubspec.yaml(要求 Dart SDKworkspace:,根目录设置^3.6.0)。运行publish_to: none(或dart pub workspace list)以识别候选成员包,并映射拓扑依赖顺序。fvm dart pub workspace list
- 单包:根目录
- 远程与本地版本基线:
- 查询 pub.dev API(),确定远程线上版本(如果返回 404,则标记为 UNPUBLISHED)。
curl -s https://pub.dev/api/packages/<pkg> - 读取本地清单版本()。
grep '^version:' <pubspec.yaml> - 比较远程版本与本地版本,建立版本提案基线:未升级()、工作区中已预先升级(
Local == Remote),或首次发布(Local > Remote)。UNPUBLISHED
- 查询 pub.dev API(
Phase 2: Preflight Quality Gate
阶段 2:预检质量门禁
Run formatting (), analyzer checks (), changelog readiness, and test suites across the target release scope. If any verification fails, report diagnostics and halt immediately.
dart format --output=none --set-exit-if-changed .dart analyze --fatal-infos在目标发布范围内运行格式化()、静态分析器检查()、变更日志就绪性检查和测试套件。如果任何验证失败,则报告诊断信息并立即终止。
dart format --output=none --set-exit-if-changed .dart analyze --fatal-infosPhase 3: Version Proposal & Turn-Halt Gate
阶段 3:版本提案与终止门禁
- Assess changeset scope across the target package(s) (breaking, feat, fix).
- Present release proposal:
- Single Package: Propose recommended SemVer candidate grounded against remote baseline (and optional pre-release preview if applicable).
- Pub Workspace: Present Release Matrix listing affected packages in topological order, Remote Live vs Local version, proposed version, and downstream constraint cascades.
- CI Workflow Addition: If user elected in Phase 1 to seed a publish workflow, include in the proposed changeset.
.github/workflows/publish.yml
- Halt turn immediately. Forbid modifying manifests or git history until the user selects or approves the version proposal.
- 评估目标包的变更集范围(breaking、feat、fix)。
- 提出发布方案:
- 单包:以远程版本基线为依据,提出推荐的 SemVer 候选版本(如果适用,也可附带预发布预览版本)。
- Pub Workspace:呈现发布矩阵,按拓扑顺序列出受影响的包、远程线上版本与本地版本、建议版本以及下游约束的级联影响。
- CI 工作流新增:如果用户在阶段 1 中选择初始化发布工作流,则将 纳入建议的变更集。
.github/workflows/publish.yml
- 立即终止本轮操作。在用户选择或批准版本提案之前,禁止修改清单或 Git 历史记录。
Phase 4: Manifest Mutation, Dry-Run Verification & Handoff
阶段 4:清单变更、Dry-Run 验证与交接
- Manifest & Changelog Synchronization: Upon user approval, synchronize versions across target manifests, per-package
pubspec.yamlfiles, and seedCHANGELOG.md(if requested)..github/workflows/publish.yml - Atomic Release Commit: Stage updated files and amend HEAD () or create an atomic release commit (
git commit --amend --no-edit).git commit -m "chore(release): publish packages [...]" - Last Verification (Dry-Run): Execute package manager publication dry-run sequentially in topological order:
- Single Package:
dart pub publish --dry-run - Pub Workspace: for each approved package.
dart pub -C <package_dir> publish --dry-run - If errors, warnings, or archive leaks occur, supply exact failure diagnostics and halt immediately.
- Single Package:
- Publication Readiness Report & Tailored Handoff:
- Present dry-run confirmation and topological release sequence.
- Tailor handoff instructions to the publishing setup aligned in Phase 1:
- CI-Driven (Tag Push): Deliver exact Git tag commands matching the repo's tag pattern (e.g. for single,
v<version>for workspace) pointing to the release commit SHA, and tag push commands.<package>-v<version> - Terminal/CMD: Deliver direct publish commands (/
dart pub publishin topological order, noting the 120s pub.dev CDN propagation window; seedart pub -C <package_dir> publish).references/pub-workspace-workflow.md
- CI-Driven (Tag Push): Deliver exact Git tag commands matching the repo's tag pattern (e.g.
- 清单与变更日志同步:获得用户批准后,同步目标 清单、各包的
pubspec.yaml文件中的版本信息,并按需初始化CHANGELOG.md。.github/workflows/publish.yml - 原子发布提交:暂存更新后的文件并 amend HEAD(),或者创建一次原子发布提交(
git commit --amend --no-edit)。git commit -m "chore(release): publish packages [...]" - 最终验证(Dry-Run):按拓扑顺序依次执行包管理器发布 dry-run:
- 单包:
dart pub publish --dry-run - Pub Workspace:对每个已批准的包执行 。
dart pub -C <package_dir> publish --dry-run - 如果出现错误、警告或 archive leaks,则提供准确的失败诊断信息并立即终止。
- 单包:
- 发布就绪报告与定制化交接:
- 呈现 dry-run 确认结果和拓扑发布顺序。
- 根据阶段 1 中确定的发布设置定制交接说明:
- CI 驱动(推送标签):提供与仓库标签模式完全匹配的 Git 标签命令(例如,单包使用 ,Workspace 使用
v<version>),使其指向发布提交 SHA,并提供标签推送命令。<package>-v<version> - 终端/CMD:提供直接发布命令(或
dart pub publish),并按拓扑顺序执行,同时提示 pub.dev CDN 的 120 秒传播窗口;参见dart pub -C <package_dir> publish。references/pub-workspace-workflow.md
- CI 驱动(推送标签):提供与仓库标签模式完全匹配的 Git 标签命令(例如,单包使用