dart-package-maintenance

Original：🇺🇸 English

Translated

Guidelines for maintaining external Dart packages, covering versioning, publishing workflows, and pull request management. Use when updating Dart packages, preparing for a release, or managing collaborative changes in a repository.

2installs

Sourcekevmoo/dash_skills

Added on2026-03-06

NPX Install

npx skill4agent add kevmoo/dash_skills dart-package-maintenance

SKILL.md Content

View Translation Comparison →

Dart Package Maintenance

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

Versioning

Semantic Versioning

Major: Breaking changes.
Minor: New features (non-breaking API changes).
Patch: Bug fixes, documentation, or non-impacting changes.
Unstable packages: Use
```
0.major.minor+patch
```
.
Recommendation: Aim for
```
1.0.0
```
as soon as the package is stable.

Pre-Edit Verification

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
    ).

Work-in-Progress (WIP) Versions

Immediately after a publish, or on the first change after a publish, update
```
pubspec.yaml
```
and
```
CHANGELOG.md
```
with a
```
-wip
```
suffix (e.g.,
```
1.1.0-wip
```
).
This indicates the current state is not yet published.

Breaking Changes

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.

Publishing Process

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
```

Pull Request Management

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.