dart-package-maintenance

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Chinese

Guidelines for maintaining Dart packages in alignment with Dart team best practices.

符合Dart团队最佳实践的Dart包维护指南。

Check Published Versions: Before modifying
```
CHANGELOG.md
```
or
```
pubspec.yaml
```
, ALWAYS check the currently released version (e.g., via
```
git tag
```
or
```
pub.dev
```
).
Do Not Amend Released Versions: Never add new entries to a version header that corresponds to a released tag.
Increment for New Changes: If the current version in
```
pubspec.yaml
```
matches a released tag, increment the version (e.g., usually to
```
-wip
```
) and create a new section in
```
CHANGELOG.md
```
.
- Consistency: The
```
CHANGELOG.md
```
  header must match the new
```
pubspec.yaml
```
  version.
- SemVer Guidelines:
  - Breaking Changes: Bump Major, reset Minor/Patch (e.g.,
```
2.0.0-wip
```
    ,
```
0.5.0-wip
```
    ).
  - New Features: Bump Minor, reset Patch (e.g.,
```
1.1.0-wip
```
    ,
```
0.4.5-wip
```
    ).
  - Bug Fixes: Bump Patch (e.g.,
```
1.0.1-wip
```
    ).

检查已发布版本：修改
```
CHANGELOG.md
```
或
```
pubspec.yaml
```
之前，务必检查当前已发布的版本（可通过
```
git tag
```
或
```
pub.dev
```
查询）。
不得修改已发布版本：严禁在对应已发布标签的版本标题下新增更新条目。
新改动需升级版本：如果
```
pubspec.yaml
```
中的当前版本与已发布标签一致，需要升级版本号（通常添加
```
-wip
```
后缀），并在
```
CHANGELOG.md
```
中新增对应版本的更新章节。
- 一致性要求：
```
CHANGELOG.md
```
  中的版本标题必须与
```
pubspec.yaml
```
  中的新版本号完全一致。
- 语义化版本规范：
  - 破坏性变更：升级主版本号，重置次版本号和修订号（例如
```
2.0.0-wip
```
    、
```
0.5.0-wip
```
    ）。
  - 新增功能：升级次版本号，重置修订号（例如
```
1.1.0-wip
```
    、
```
0.4.5-wip
```
    ）。
  - 漏洞修复：升级修订号（例如
```
1.0.1-wip
```
    ）。

Evaluate the impact on dependent packages and internal projects.
Consider running changes through internal presubmits if possible.
Prefer incremental rollouts (e.g., new behavior as opt-in) to minimize downstream breakage.

Preparation: Remove the
```
-wip
```
suffix from
```
pubspec.yaml
```
and
```
CHANGELOG.md
```
in a dedicated pull request.
Execution: Run
```
dart pub publish
```
(or
```
flutter pub publish
```
) and resolve all warnings and errors.
Tagging: Create and push a git tag for the published version:
- For single-package repos:
```
v1.2.3
```
- For monorepos:
```
package_name-v1.2.3
```
- Example:
```
git tag v1.2.3 && git push --tags
```

准备工作：在单独的拉取请求中移除
```
pubspec.yaml
```
和
```
CHANGELOG.md
```
版本号中的
```
-wip
```
后缀。
执行发布：运行
```
dart pub publish
```
（或
```
flutter pub publish
```
）命令，解决所有警告和错误。
打标签：为已发布的版本创建并推送git标签：
- 单包仓库：格式为
```
v1.2.3
```
- 多包monorepo仓库：格式为
```
包名-v1.2.3
```
- 示例命令：
```
git tag v1.2.3 && git push --tags
```

Commits: Each PR should generally correspond to a single squashed commit upon merging.
Shared History: Once a PR is open, avoid force pushing to the branch.
Conflict Resolution: Prefer merging
```
main
```
into the PR branch rather than rebasing to resolve conflicts. This preserves the review history and comments.
Reviewing: Add comments from the "Files changed" view to batch them.
Local Inspection: Use
```
gh pr checkout <number>
```
to inspect changes locally in your IDE.