ci-pub

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ci-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:环境与发布设置发现

  1. Publishing Strategy & CI Audit:
    • Inspect
      .github/workflows/
      for existing release/publish workflows (e.g.
      publish.yml
      ,
      release.yml
      ). Identify configured trigger mechanisms: tag-driven OIDC (
      refs/tags/*
      ), manual dispatch (
      workflow_dispatch
      ), or absent (terminal/cmd driven).
    • CI Seeding Gate (If No CI Configured): If
      .github/workflows/
      lacks a publish workflow, highlight that no automated CI was detected and offer to seed one from
      references/workflow-single.yml
      or
      references/workflow-workspace.yml
      (to be committed atomically with the release).
    • Read repository publishing documentation and runbooks (
      doc/runbooks/*publish*.md
      ,
      docs/*release*.md
      ,
      CONTRIBUTING.md
      ) to extract project-specific release invariants and packaging constraints.
  2. Topology & Member Mapping:
    • Single Package: Root
      pubspec.yaml
      without
      workspace:
      directive.
    • Pub Workspace: Root
      pubspec.yaml
      contains
      workspace:
      (requires Dart SDK
      ^3.6.0
      , root
      publish_to: none
      ). Run
      dart pub workspace list
      (or
      fvm dart pub workspace list
      ) to identify candidate member packages and map topological dependency order.
  3. Remote & Local Version Baseline:
    • Query pub.dev API (
      curl -s https://pub.dev/api/packages/<pkg>
      ) to resolve Remote Live Version (or mark
      UNPUBLISHED
      if 404).
    • Read Local Manifest Version (
      grep '^version:' <pubspec.yaml>
      ).
    • Compare Remote vs Local to baseline the proposal: unbumped (
      Local == Remote
      ), pre-bumped in working tree (
      Local > Remote
      ), or initial release (
      UNPUBLISHED
      ).
  1. 发布策略与 CI 审计:
    • 检查
      .github/workflows/
      中现有的发布或发布工作流(例如
      publish.yml
      、
      release.yml
      )。识别已配置的触发机制:标签驱动的 OIDC(
      refs/tags/*
      )、手动触发(
      workflow_dispatch
      ),或未配置(由 terminal/cmd 驱动)。
    • 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 Workspace:根目录
      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
      )。

Phase 2: Preflight Quality Gate

阶段 2:预检质量门禁

Run formatting (
dart format --output=none --set-exit-if-changed .
), analyzer checks (
dart analyze --fatal-infos
), 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
)、变更日志就绪性检查和测试套件。如果任何验证失败,则报告诊断信息并立即终止。

Phase 3: Version Proposal & Turn-Halt Gate

阶段 3:版本提案与终止门禁

  1. Assess changeset scope across the target package(s) (breaking, feat, fix).
  2. 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
      .github/workflows/publish.yml
      in the proposed changeset.
  3. Halt turn immediately. Forbid modifying manifests or git history until the user selects or approves the version proposal.
  1. 评估目标包的变更集范围(breaking、feat、fix)。
  2. 提出发布方案:
    • 单包:以远程版本基线为依据,提出推荐的 SemVer 候选版本(如果适用,也可附带预发布预览版本)。
    • Pub Workspace:呈现发布矩阵,按拓扑顺序列出受影响的包、远程线上版本与本地版本、建议版本以及下游约束的级联影响。
    • CI 工作流新增:如果用户在阶段 1 中选择初始化发布工作流,则将
      .github/workflows/publish.yml
      纳入建议的变更集。
  3. 立即终止本轮操作。在用户选择或批准版本提案之前,禁止修改清单或 Git 历史记录。

Phase 4: Manifest Mutation, Dry-Run Verification & Handoff

阶段 4:清单变更、Dry-Run 验证与交接

  1. Manifest & Changelog Synchronization: Upon user approval, synchronize versions across target
    pubspec.yaml
    manifests, per-package
    CHANGELOG.md
    files, and seed
    .github/workflows/publish.yml
    (if requested).
  2. Atomic Release Commit: Stage updated files and amend HEAD (
    git commit --amend --no-edit
    ) or create an atomic release commit (
    git commit -m "chore(release): publish packages [...]"
    ).
  3. Last Verification (Dry-Run): Execute package manager publication dry-run sequentially in topological order:
    • Single Package:
      dart pub publish --dry-run
    • Pub Workspace:
      dart pub -C <package_dir> publish --dry-run
      for each approved package.
    • If errors, warnings, or archive leaks occur, supply exact failure diagnostics and halt immediately.
  4. 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.
        v<version>
        for single,
        <package>-v<version>
        for workspace) pointing to the release commit SHA, and tag push commands.
      • Terminal/CMD: Deliver direct publish commands (
        dart pub publish
        /
        dart pub -C <package_dir> publish
        in topological order, noting the 120s pub.dev CDN propagation window; see
        references/pub-workspace-workflow.md
        ).
  1. 清单与变更日志同步:获得用户批准后,同步目标
    pubspec.yaml
    清单、各包的
    CHANGELOG.md
    文件中的版本信息,并按需初始化
    .github/workflows/publish.yml
    。
  2. 原子发布提交:暂存更新后的文件并 amend HEAD(
    git commit --amend --no-edit
    ),或者创建一次原子发布提交(
    git commit -m "chore(release): publish packages [...]"
    )。
  3. 最终验证(Dry-Run):按拓扑顺序依次执行包管理器发布 dry-run:
    • 单包:
      dart pub publish --dry-run
    • Pub Workspace:对每个已批准的包执行
      dart pub -C <package_dir> publish --dry-run
      。
    • 如果出现错误、警告或 archive leaks,则提供准确的失败诊断信息并立即终止。
  4. 发布就绪报告与定制化交接:
    • 呈现 dry-run 确认结果和拓扑发布顺序。
    • 根据阶段 1 中确定的发布设置定制交接说明:
      • CI 驱动(推送标签):提供与仓库标签模式完全匹配的 Git 标签命令(例如,单包使用
        v<version>
        ,Workspace 使用
        <package>-v<version>
        ),使其指向发布提交 SHA,并提供标签推送命令。
      • 终端/CMD:提供直接发布命令(
        dart pub publish
        或
        dart pub -C <package_dir> publish
        ),并按拓扑顺序执行,同时提示 pub.dev CDN 的 120 秒传播窗口;参见
        references/pub-workspace-workflow.md
        。