bump-version

name	bump-version
description	Bumps the very_good_analysis package to a new version. Use when preparing a release, adding support for a new Dart SDK, or adding/removing lint rules — even for phrasings like "bump version", "cut a release", or "add rules for Dart X.Y".

Bump Version — very_good_analysis

Overview

This skill guides the full version bump workflow for the very_good_analysis package. It uses the project's own tool/bump_version Dart script and enforces the constraints from the project's release process.

Key Constraints

These rules are critical. Violating some of them will cause CI to fail.

1. pubspec.yaml version is NOT bumped here. The version in pubspec.yaml is managed exclusively by release-please. Do not change it.
2. lib/analysis_options.yaml MUST point to the new version. The bump_version tool handles this automatically.
3. A new lib/analysis_options.<version>.yaml MUST exist. The bump_version tool creates it by copying the previous version's file.
4. The latest_vga_version_test.dart expected version MUST match the version referenced in lib/analysis_options.yaml.
5. The tool/linter_rules tests must pass — they validate the consistency of the linter rules tooling.
6. All changes go on a feature branch, never directly on main.
7. Commit messages must follow Conventional Commits (e.g. feat:, fix:).

Inputs

Parameter	Description	Required
version	New version string in x.y.z format (e.g. 10.4.0)	Ask if not provided

If version is not provided, ask:

"What version do you want to bump to? (e.g. 10.4.0)"

Validate the format matches \d+\.\d+\.\d+ before proceeding.

Workflow

Step 1 — Confirm the version

• If the user provided a version, confirm it looks correct.
• Validate it is greater than the current version in lib/analysis_options.yaml (read it with the Dart MCP read_package_uris tool or the Read file tool).

Step 2 — Run the bump_version tool

Run from the project root:

dart tool/bump_version/lib/bump_version.dart <NEW_VERSION>

This will:

• Copy lib/analysis_options.<current>.yaml → lib/analysis_options.<new>.yaml
• Update lib/analysis_options.yaml to include: the new versioned file

Do NOT manually edit lib/analysis_options.yaml or create the versioned file by hand. Always use the tool.

Step 3 — Update the linter rules test

The file tool/linter_rules/test/src/latest_vga_version_test.dart contains a hardcoded expected version:

expect(version, equals('<CURRENT_VERSION>'));

Update it to match <NEW_VERSION>. This test reads lib/analysis_options.yaml at runtime, so it must stay in sync.

Step 4 — (Optional) Update lint rules in the new file

If the purpose of the bump is to add/remove rules or incorporate new Dart SDK rules, edit lib/analysis_options.<NEW_VERSION>.yaml now.

For new Dart SDK rules, also run the exclusion reason table generator. Fetch the tool's dependencies first, since tool/linter_rules is a separate package with its own pubspec.yaml:

# From tool/linter_rules directory
dart pub get
dart lib/exclusion_reason_table.dart

Step 5 — Verify with static analysis

Prefer the Dart MCP analyze_files tool if available. Otherwise use the CLI:

# From project root
dart analyze lib example
dart format --set-exit-if-changed lib example

The ci workflow only analyzes lib and example, but this workflow also edits tool/linter_rules/test/src/latest_vga_version_test.dart. That directory is validated by a separate CI workflow (tool_linter_rules.yaml), so verify it locally too:

# From tool/linter_rules directory
dart pub get
dart format --set-exit-if-changed .
dart analyze .

Step 6 — Run the linter_rules tool tests

Prefer the Dart MCP tools if available. Otherwise (skip dart pub get if you already ran it in a previous step):

# From tool/linter_rules directory
dart pub get
dart test

All tests must pass, including:

• latestVgaVersion returns the latest very good analysis version
• All other tests in tool/linter_rules/test/

Step 7 — Understand verify_version (do NOT run it here)

Do not run tool/verify_version/main.dart as part of this workflow. It will fail by design, and that failure is meaningless at this stage.

The verify_version script compares the pubspec.yaml version against the version referenced in lib/analysis_options.yaml. In this workflow pubspec.yaml is intentionally NOT bumped (it stays behind, managed by release-please), so the two versions will not match and the script will exit with code 1.

The CI verify_version workflow reflects this: it is gated to run only on the release-please branch (release-please--branches--main--components--very_good_analysis). It passes only after release-please opens its release PR and bumps pubspec.yaml to match. There is nothing to verify locally during the feature PR.

Step 8 — Commit

Stage only the relevant files:

lib/analysis_options.yaml
lib/analysis_options.<NEW_VERSION>.yaml
tool/linter_rules/test/src/latest_vga_version_test.dart

Do NOT stage pubspec.yaml unless the SDK constraint also needs updating (e.g. when adopting a new Dart SDK version).

Commit message must follow Conventional Commits. Since PRs are squash-merged, the commit subject and the PR title end up being the same thing — so keep them consistent. Prefer the title that the semantic-pull-request check expects (see Step 9):

• Upgrading to a new Dart SDK → feat: upgrade to Dart <NEW_SDK_VERSION>
• Adding/removing lint rules (no SDK change) → feat: add analysis_options.<version>.yaml
• Bug fix in rules → fix: update analysis_options.<version>.yaml

Step 9 — Push and open PR

Push to the feature branch and open a PR against main.

PR title must follow Conventional Commits to satisfy the semantic-pull-request CI check, and should match the commit subject from Step 8 (PRs are squash-merged):

• When the bump tracks a new Dart SDK (the common case):

  feat: upgrade to Dart <NEW_SDK_VERSION>
  

  where <NEW_SDK_VERSION> is the Dart SDK version associated with the very_good_analysis version being added (e.g. feat: upgrade to Dart 3.9).
• When the bump only adds/removes lint rules with no SDK change:

  feat: add analysis_options.<NEW_VERSION>.yaml
  

PR description — before opening the PR, search the GitHub repo VeryGoodOpenSource/very_good_analysis for an open issue requesting this bump (typically titled something like feat: add analysis_options.<NEW_VERSION>.yaml for Dart <NEW_SDK_VERSION>).

Use the GitHub MCP server's issue search tool (its exact name depends on your environment — e.g. search_issues) with a query like: repo:VeryGoodOpenSource/very_good_analysis analysis_options.<NEW_VERSION>.yaml

If the GitHub MCP tools are unavailable, fall back to the CLI: gh issue list --repo VeryGoodOpenSource/very_good_analysis --search "analysis_options.<NEW_VERSION>.yaml"

If a matching issue is found, append the following line to the PR description:

Closes #<ISSUE_NUMBER>.

If no matching issue exists, omit the closing line.

File Map

File	Role
lib/analysis_options.yaml	Default include — always points to latest versioned file
lib/analysis_options.<version>.yaml	Versioned snapshot of all lint rules
pubspec.yaml	Package version — managed by release-please, do NOT bump manually
tool/bump_version/lib/bump_version.dart	Script that creates the new versioned file and updates the default
tool/linter_rules/test/src/latest_vga_version_test.dart	Must match the version in lib/analysis_options.yaml
tool/linter_rules/lib/exclusion_reason_table.dart	Regenerates the exclusion table (run when adding new SDK rules)
tool/verify_version/main.dart	Verifies pubspec version matches analysis_options version (release-please PRs only)

Release Process (for context)

This skill prepares the feature PR. The release itself is automated:

1. Feature PR is merged to main with a feat: commit.
2. release-please detects the conventional commit and opens a release PR (titled chore: <version>, per .release-please-config.json) that bumps pubspec.yaml and updates CHANGELOG.md.
3. When the release PR is merged, a tag is created and the package is published to pub.dev automatically.

Never bump pubspec.yaml manually. Let release-please do it.

Example Session

User: bump version to 10.4.0

Agent:
1. Reads lib/analysis_options.yaml → current version is 10.3.0 ✓
2. Runs: dart tool/bump_version/lib/bump_version.dart 10.4.0
   → Creates lib/analysis_options.10.4.0.yaml
   → Updates lib/analysis_options.yaml to include 10.4.0
3. Updates latest_vga_version_test.dart: expects('10.4.0')
4. Runs dart analyze/format on lib example AND tool/linter_rules → clean ✓
5. Runs dart pub get + dart test in tool/linter_rules → all pass ✓
   (Skips tool/verify_version — it fails by design until release-please runs)
6. Commits (subject matches the PR title, since PRs squash-merge):
   feat: upgrade to Dart 3.13
7. Searches GitHub for an issue matching
   "feat: add analysis_options.10.4.0.yaml for Dart 3.13"
   → Found issue #673 ✓
8. Pushes and opens PR:
   Title: feat: upgrade to Dart 3.13
   Body:  ...
          Closes #673.