Dart Package Maintenance

---
name: dart-package-maintenance
description: |-
  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.
key_features:
  - Versioning & CHANGELOG sync
  - Publishing workflow guidelines
  - Pull request management
---

# Dart Package Maintenance

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

## 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).
- **Documentation or Skill-Only Changes**: Pull requests that only modify
  markdown files, agent skills (`SKILL.md`), or repository documentation, as
  documentation updates do not alter the public package interface.
- **In-Flight PR Iterations**: Intermediate commits on an active feature branch
  where the version already carries a `-wip` suffix. Do not bump the version on
  every commit.

## Discovery

To find maintenance tasks or inconsistencies:

### Consistency Checks

Ensure the latest version in `CHANGELOG.md` matches `pubspec.yaml`:

- Compare the top header in `CHANGELOG.md` with the `version:` field in
  `pubspec.yaml`.

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

### Changelog Content

- **Focus on User Impact**: Entries in `CHANGELOG.md` should focus on changes
  visible to or impacting the end-user (e.g., new features, bug fixes, breaking
  changes).
- **Omit Internal Changes**: Do not include internal refactorings, test changes,
  or other modifications that do not affect the package's behavior or API for
  the user.

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

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.