Bump Version

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

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.