Dart Version Bumping Skill

When to use this skill

Use this skill when:

• •You are asked to bump versions in a Dart or Flutter workspace / monorepo
• •All packages share a single version
• •Compatibility is guaranteed only for identical versions across packages
• •Versions and releases are managed centrally
• •CHANGELOG.md exists at the repository root

Versioning Model

This repository uses lockstep workspace versioning:

• •All packages share one identical version
• •Every release publishes all packages
• •Version equality guarantees compatibility across packages
• •Compatibility across different versions is NOT guaranteed

Packages are distribution units, not independently versioned products.

Source of Truth

The only source of truth for version decisions is:

/CHANGELOG.md → ## [Unreleased]

• •There is exactly one canonical CHANGELOG.md at the repository root
• •Package-level CHANGELOG.md files are derived artifacts
• •Package CHANGELOG.md files must not be edited manually

Content outside ## [Unreleased] must be ignored for version decisions.

Semantic Versioning Rules

Versions follow:

MAJOR.MINOR.PATCH

Exactly one increment must be applied.

Major Version Bump

Apply a major bump if and only if:

• •A section named ### BREAKING exists under ## [Unreleased]
• •Or any entry explicitly describes a breaking change

Result:

MAJOR = MAJOR + 1
MINOR = 0
PATCH = 0

Minor Version Bump

Apply a minor bump if and only if:

• •No ### BREAKING section exists
• •New functionality is introduced via:
  • •### Added
  • •### Features
  • •### Changed (non-breaking)

Result:

MINOR = MINOR + 1
PATCH = 0

Patch Version Bump

Apply a patch bump if and only if:

• •No breaking changes
• •No new features
• •Only fixes or maintenance work exist

Typical sections:

• •### Fixed
• •### Refactored
• •### Docs
• •### Chore

Result:

PATCH = PATCH + 1

Required Actions

1. Determine the Next Version

1. •Read the current version from any pubspec.yaml (all versions are identical)
2. •Parse /CHANGELOG.md
3. •Extract ## [Unreleased]
4. •Determine the bump type using the rules above
5. •Compute the next workspace version

2. Update pubspec.yaml Files

For every package in the workspace:

• •Update the version: field to the new version
• •Preserve formatting
• •Do not modify dependencies
• •Do not introduce per-package version differences

3. Update the Root CHANGELOG.md

• •

  Rename ## [Unreleased] to:

  [<new_version>] - <yyyy-MM-dd>

• •

  Use the current date in yyyy-MM-dd format

• •

  Insert a new empty ## [Unreleased] section above it

• •

  Preserve all existing content and ordering

4. Package CHANGELOG Handling (Important)

• •Do NOT maintain or edit package-level CHANGELOG.md files
• •During publishing, the root CHANGELOG.md is copied into each package directory
• •This is a publish-time operation only
• •Package CHANGELOG.md files are not authoritative

Multi-Package Repositories

• •Versioning is evaluated once per workspace
• •All packages receive the same version
• •Independent package versioning is explicitly forbidden
• •Do not attempt to infer per-package changes

Constraints

The agent must NOT:

• •Evaluate packages independently
• •Assign different versions to different packages
• •Parse or interpret package-level CHANGELOG.md files
• •Guess version numbers
• •Skip versions
• •Apply multiple version increments
• •Bump versions if ## [Unreleased] is empty
• •Modify unrelated files

Completion Criteria

The task is complete when:

• •The root CHANGELOG.md is updated correctly
• •All pubspec.yaml files contain the new identical version
• •A fresh empty ## [Unreleased] section exists
• •No package-level changelog logic was introduced
• •No unrelated changes exist