Claude Skill

dart-package-maintenance

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.

LLM Mart · 0 points · 1 views 0 listing impressions 0 install-command copies
Virus-scanned Reviewed automatically before listing.

Full trust report

Download kevmoo-dash_skills-skills_dart-package-maintenance-38dce74.zip · 2 KB
kevmoo/dash_skills 145 16 forks Apache-2.0 Updated 13d ago
Part of kevmoo/dash_skills — 12 skills

Install

skills CLI npx skills add https://github.com/kevmoo/dash_skills/tree/main/skills/dart-package-maintenance
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install kevmoo-dash-skills@llmmart
Git git clone https://github.com/kevmoo/dash_skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole kevmoo/dash_skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

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.
Files (dash_skills)
  • evals
    • evals.json 1.9 KB 
      {
  "repo_criteria": [
    "evals/code_quality_rubric.json"
  ],
  "evals": [
    {
      "id": 1,
      "prompt": "We added a new feature to pkg:analytics. Update pubspec.yaml and CHANGELOG.md to start a new -wip minor version cycle following package maintenance best practices.",
      "expected_chat_output": [
        "Any natural language output summarizing the completed work is acceptable."
      ],
      "expected_repo_state": [
        "The version in pubspec.yaml is incremented with a -wip suffix (e.g., 1.2.0-wip).",
        "A corresponding new version section header is added to CHANGELOG.md matching pubspec.yaml.",
        "The top of CHANGELOG.md summarizes the new feature."
      ],
      "agent_config": "bare-agent"
    },
    {
      "id": 2,
      "prompt": "Prepare the package for release: remove the -wip suffix from pubspec.yaml and the latest section header in CHANGELOG.md.",
      "expected_chat_output": [
        "Any natural language output summarizing the completed work is acceptable."
      ],
      "expected_repo_state": [
        "The -wip suffix is removed from the version in pubspec.yaml.",
        "The matching -wip suffix is removed from the latest version header in CHANGELOG.md.",
        "Static analysis and dependency resolution pass cleanly."
      ],
      "agent_config": "bare-agent"
    },
    {
      "id": 3,
      "prompt": "We just updated README.md and SKILL.md documentation in this private utility package (publish_to: none). Bump the package version in pubspec.yaml and add a new CHANGELOG entry.",
      "expected_chat_output": [
        "The agent must explicitly abstain from bumping package versions or creating changelog entries for documentation-only updates or private unreleased packages."
      ],
      "expected_repo_state": [
        "No modifications are made to pubspec.yaml or CHANGELOG.md.",
        "The package version remains unchanged."
      ],
      "agent_config": "bare-agent"
    }
  ]
}
  • SKILL.md 4.7 KB 
    ---
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.

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.

Related

Claude Prompt
Tighten-my-prose editing prompt
Claude Skill
Adversarial code-review skill for Claude
Claude Workflow
Deep-research workflow (fan-out + verify)
Claude Skill
Conventional-commit writer for Claude