SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场dart-package-maintenance

dart-package-maintenance

编程与开发

查看项目

更新于 10-15 16:25

技能介绍

用途

Dart Package Maintenance 是一套用于维护外部 Dart 包的指南，旨在与 Dart 团队的外部包维护规范保持一致。它适用于以下场景：更新 Dart 包、准备发布、管理仓库中的协作变更；管理版本号、CHANGELOG.md 同步与发布工作流；确保已发布的包符合 Dart 团队约定。

不适用场景（弃权护栏）

以下情况不应应用包维护的版本递增或变更日志更新：

  • 内部/私有包：在 pubspec.yaml 中标记为 publish_to: none、未发布到 pub.dev 的包（例如应用根包或内部 monorepo 工具）。
  • 仓库根级文件或历史 CHANGELOG.md 拼写错误：仅修改已发布包之外的仓库级文件（如 .github/workflows/、仓库根 SKILL.md 或 monorepo 根文档）的 PR，或仅修复历史 CHANGELOG.md 章节中拼写/格式的 PR。
  • 进行中的 PR 提交：活跃功能分支上的中间提交，且版本已带有合适的 -wip 后缀。

版本管理

语义化版本

Dart 包使用语义化版本，并在 1.0.0 之前采用变体：版本号在 1.0.0 发布前向右偏移；另见 package:pub_semver 语义：

  • 1.0.0 或更高版本：major.minor.patch。
  • 尚未达到 1.0.0 的包：0.major.minor，其中第二个数字用于破坏性变更（如 0.4.2 到 0.5.0-wip），第三个数字用于非破坏性功能和错误修复（如 0.4.2 到 0.4.3-wip）。避免使用 +1 构建后缀（在 package:pub_semver 中，0.4.2+1-wip 会将 +1-wip 解析为构建元数据，而非 -wip 预发布版本）。

建议：包稳定后尽快发布 1.0.0。

根据变更影响选择版本递增：

  • Major：破坏性变更，包括移除或重命名 pubspec.yaml 的 executables 条目。
  • Minor：新功能和非破坏性 API 变更，例如引入新类或添加 pubspec.yaml 的 executables 条目。
  • Patch：错误修复、最低 environment.sdk 或运行时依赖约束更新，或任何不影响调用代码的变更。

更新版本

只要仓库中的代码与 pub.dev 上发布的最新版本不同，pubspec.yaml 和 CHANGELOG.md 都必须使用 -wip 版本。在发布后的第一次变更时就递增到 -wip，即使不打算以该状态发布，或该变更不影响使用者。

打开或合并 PR 时，检查 pubspec.yaml 和 CHANGELOG.md 中的当前版本：

  • 当前为已发布版本（如 1.2.3）：执行适当的版本递增，在 pubspec.yaml 中追加 -wip，并在 CHANGELOG.md 顶部添加匹配的 ## <version>-wip 章节。
  • 已处于 -wip 版本（如 1.2.4-wip）：将现有 -wip 递增与你的变更所需递增进行比较。如果变更需要更大的递增（例如添加功能时从 patch 递增到 minor 递增），则更新 pubspec.yaml 并就地重命名 CHANGELOG.md 中现有的 ## <version>-wip 标题。
  • 尚未发布到 pub.dev，处于 0.1.0-wip：保持 0.1.0-wip 和 - Initial release. 条目，在首次发布前不添加逐 PR 的变更日志条目。

更新 CHANGELOG.md

  • 用户可见变更：在顶部 -wip 章节下添加条目。
  • 内部或非用户可见变更（如安全重构、lint 清理、test/、tool/ 或 README.md 更新，或 dev_dependencies 和 dependency_overrides 变更）：
    • 如果你的 PR 创建了新的 -wip 章节，添加 ## <version>-wip 标题，其下不添加任何项目符号。
    • 如果包已处于 -wip 版本，保持 CHANGELOG.md 不变，并应用 skip-changelog-check PR 标签。
  • 对未发布工作的后续编辑：如果后续 PR 修改或回退了当前 -wip 章节中的未发布变更（例如在发布前再次递增 SDK 或依赖约束），则就地更新或移除现有 -wip 项目符号，而不是添加重复条目。
  • 已发布章节：绝不在已发布版本标题下添加新条目，尤其是在 PR 打开期间发布落地后合并 main 时。

破坏性变更

  • 评估对依赖包和内部项目的影响。
  • 尽可能通过内部预提交运行变更。
  • 优先采用增量发布（例如新行为作为可选加入），以最小化下游破坏。

发布流程

  • 准备：在专用 pull request 中从 pubspec.yaml 和 CHANGELOG.md 移除 -wip 后缀。
  • 执行：运行 dart pub publish（或 flutter pub publish），并解决所有警告和错误。
  • 打标签：为已发布版本创建并推送 git 标签：
    • 单包仓库：v1.2.3
    • monorepo：package_name-v1.2.3
    • 示例：git tag v1.2.3 && git push --tags

Pull Request 管理

  • 提交：每个 PR 在合并时通常应对应一个压缩提交。
  • 共享历史：PR 打开后，避免强制推送到分支。
  • 冲突解决：优先将 main 合并到 PR 分支，而不是变基，以保留审查历史和评论。
  • 审查：从 "Files changed" 视图添加评论以批量处理。
  • 本地检查：使用 gh pr checkout <number> 在 IDE 中本地检查变更。