dart-package-maintenance

Dart Package 维护

根据 Dart 团队规范维护 Dart Package： 外部 Package 维护。

何时使用此技能

在以下情况下使用此技能：

• 更新 Dart Package、准备发布，或管理仓库中的协作变更。
• 管理版本号、同步 CHANGELOG.md 和发布工作流。
• 确保已发布的 Package 符合 Dart 团队惯例。

何时不使用（弃答防护措施）

在以下情况下，不要应用 Package 维护版本升级或更新变更日志：

• 内部／私有 Package：在 pubspec.yaml 中标记为 publish_to: none 且未发布到 pub.dev 的 Package（例如应用根 Package 或内部单体仓库工具）。
• 仓库根目录文件或历史 CHANGELOG.md 拼写错误：仅修改已发布 Package 之外的仓库级文件（例如 .github/workflows/、仓库根目录的 SKILL.md 或单体仓库中的根目录文档），或仅修正历史 CHANGELOG.md 部分中的拼写／格式错误的拉取请求。
• 进行中的 PR 提交：活动功能分支上的中间提交，其中版本号已带有适当的 -wip 后缀。

版本管理

语义化版本

Dart Package 使用语义化版本，并在 1.0.0 发布前采用一种变体，即版本号会向右偏移；另请参阅 package:pub_semver 语义：

• 1.0.0 或更高版本的 Package：major.minor.patch。
• 尚未达到 1.0.0 的 Package：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 预发布版本）。
• 建议：Package 稳定后，尽早发布 1.0.0。

根据变更的影响选择版本升级级别：

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

更新版本号

只要仓库中的代码与 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， 并为 PR 添加 skip-changelog-check 标签。
• 对尚未发布的更改进行后续编辑：如果后续 PR 修改或撤销当前 -wip 部分中的未发布更改，例如在发布前再次提升 SDK 或依赖项约束，请原地更新或移除现有的 -wip 项目符号条目，而不要添加重复条目。
• 已发布的部分：绝不要在已发布版本标题下添加新条目，尤其是在合并 main 后，若 PR 尚未合并期间已有版本发布。

重大更改

• 评估对依赖软件包和内部项目的影响。
• 如果可行，请考虑通过内部预提交检查运行更改。
• 优先采用渐进式发布（例如，将新行为设为可选），以尽量减少对下游的影响。

发布流程

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

拉取请求管理

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