Dart Package Maintenance

Dart Package Maintenance

Guidelines for maintaining Dart packages in alignment with the canonical Dart team External Package Maintenance specification.

When to use this skill

Use this skill when:

• Updating Dart packages, preparing for a release, or managing collaborative changes in a repository.
• Managing versioning, CHANGELOG.md synchronization, and publishing workflows.
• Ensuring published packages comply with Dart team conventions.

When NOT to use (Abstention Guardrails)

Do NOT apply package maintenance version bumps or changelog updates when:

• Internal / Private Packages: Packages marked publish_to: none in pubspec.yaml that are not published to pub.dev (e.g., application root packages or internal monorepo tooling).
• Repository-Root Files or Historical CHANGELOG.md Typos: Pull requests that only modify repository-level files outside a published package (such as .github/workflows/, repo-root SKILL.md, or root docs in a monorepo) or that only fix typos/formatting in historical CHANGELOG.md sections.
• In-Flight PR Commits: Intermediate commits on an active feature branch where the version already carries an appropriate -wip suffix.

Versioning

Semantic Versioning

Dart packages use semantic versioning with a pre-1.0.0 variation where the version numbers are shifted to the right before a 1.0.0 release; see also the package:pub_semver semantics:

• Packages at 1.0.0 or later: major.minor.patch.
• Packages not yet at 1.0.0: 0.major.minor, where the second number is bumped for breaking changes, such as 0.4.2 to 0.5.0-wip, and the third number is bumped for non-breaking features and bug fixes, such as 0.4.2 to 0.4.3-wip. Avoid +1 build suffixes (in package:pub_semver, 0.4.2+1-wip parses +1-wip as build metadata rather than a -wip pre-release).
• Recommendation: Aim to publish 1.0.0 as soon as the package is stable.

Choose the version bump based on the impact of the change:

• Major: Breaking changes, including removing or renaming a pubspec.yaml executables entry.
• Minor: New features and non-breaking API changes, such as introducing a new class or adding a pubspec.yaml executables entry.
• Patch: Bug fixes, minimum environment.sdk or runtime dependencies constraint updates, or any other change that does not impact calling code.

Updating the Version

Whenever the code in the repo differs from the latest version published on pub.dev, both pubspec.yaml and CHANGELOG.md must use a -wip version. We bump to -wip on the first change after a release, even if we don't plan on publishing the code in that state or if the change doesn't impact consumers.

When opening or merging a PR, check the current version in pubspec.yaml and CHANGELOG.md:

• Currently at a published version, such as 1.2.3: Perform the appropriate version bump, append -wip in pubspec.yaml, and add a matching ## <version>-wip section at the top of CHANGELOG.md.
• Already at a -wip version, such as 1.2.4-wip: Compare the existing -wip bump against the bump required for your change. If your change requires a larger bump, such as from a patch bump to a minor bump when adding a feature, update pubspec.yaml and rename the existing ## <version>-wip heading in CHANGELOG.md in place.
• Not yet published to pub.dev, at 0.1.0-wip: Keep 0.1.0-wip and the - Initial release. entry without adding per-PR changelog entries until after the first release.

Updating CHANGELOG.md

• User-visible changes: Add an entry under the top -wip section.
• Internal or non-user-visible changes, such as safe refactorings, lint cleanups, test/, tool/, or README.md updates, or dev_dependencies and dependency_overrides changes:
  • If your PR creates the new -wip section, add the ## <version>-wip heading with no bullet items below it.
  • If the package is already at a -wip version, leave CHANGELOG.md untouched and apply the skip-changelog-check PR label.
• Follow-up edits to unreleased work: If a subsequent PR modifies or reverts an unreleased change in the current -wip section, such as bumping an SDK or dependency constraint again before publishing, update or remove the existing -wip bullet in place instead of adding a duplicate entry.
• Already-published sections: Never add new entries under an already-published version heading, especially after merging main when a release landed while your PR was open.

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

1. Preparation: Remove the -wip suffix from pubspec.yaml and CHANGELOG.md in a dedicated pull request.
2. Execution: Run dart pub publish (or flutter pub publish) and resolve all warnings and errors.
3. 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.