用途:为维护外部 Dart 包提供规范指引,使版本管理、发布流程与 PR 处理符合 Dart 团队最佳实践。
主要能力:
- 一致性检查:核对 CHANGELOG.md 顶部版本与 pubspec.yaml 的 version 字段是否一致。
- 语义化版本:Major 为破坏性变更,Minor 为新功能(非破坏性 API 变更),Patch 为缺陷修复、文档或非影响性改动;不稳定包使用 0.major.minor+patch,稳定后建议尽快到 1.0.0。
- 编辑前校验:修改 CHANGELOG.md 或 pubspec.yaml 前,务必先查已发布版本(如 git tag 或 pub.dev);不得向已发布 tag 对应的版本标题追加条目;若 pubspec.yaml 版本与已发布 tag 相同,则递增版本(通常加 -wip)并新建 CHANGELOG 段落,且两者版本须一致。
- 变更日志内容:只写对最终用户可见或产生影响的变化(新功能、缺陷修复、破坏性变更),省略内部重构与测试改动。
- WIP 版本:发布后或发布后首次改动时,立即在 pubspec.yaml 与 CHANGELOG.md 加 -wip 后缀,表示尚未发布。
- 破坏性变更:评估对依赖包与内部项目的影响,尽量走内部预提交检查,优先采用增量发布(如新行为设为可选)以减少下游破坏。
发布流程:在专门 PR 中移除 -wip 后缀;运行 dart pub publish(或 flutter pub publish)并解决所有警告与错误;为发布版本创建并推送 git tag,单包仓库用 v1.2.3,monorepo 用 package_name-v1.2.3,例如 git tag v1.2.3 && git push --tags。
PR 管理:每个 PR 合并时通常对应一个压缩提交;PR 打开后避免强制推送分支;解决冲突优先将 main 合并进 PR 分支而非 rebase,以保留评审历史与评论;评审时在 Files changed 视图批量添加评论;本地检查可用 gh pr checkout <number>。
限制:资料未提供具体工具版本、平台支持范围、收费信息或自动化脚本细节。