Skip to content

Commit 0537202

Browse files
ryzizubryzizub
committed
Merge branch 'main' into chore/update-ci
2 parents 37263fb + f0028d1 commit 0537202

6 files changed

Lines changed: 330 additions & 1 deletion

File tree

‎.claude-plugin/plugin.json‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,9 @@
4747
"theming",
4848
"very-good-cli",
4949
"wcag",
50-
"widget-testing"
50+
"widget-testing",
51+
"sdk-upgrade",
52+
"dart-sdk",
53+
"flutter-sdk"
5154
]
5255
}

‎CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ skills/
2626
bloc/SKILL.md
2727
bloc/reference.md
2828
create-project/SKILL.md
29+
dart-flutter-sdk-upgrade/SKILL.md
2930
internationalization/SKILL.md
3031
layered-architecture/SKILL.md
3132
layered-architecture/reference.md

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@ For more details, see the [Very Good Claude Marketplace][marketplace_link].
3838
| [**Layered Architecture**](skills/layered-architecture/SKILL.md) | VGV layered architecture — four-layer package structure (Data, Repository, Business Logic, Presentation), dependency rules, data flow, and bootstrap wiring |
3939
| [**Security**](skills/static-security/SKILL.md) | Flutter-specific static security review — secrets management, `flutter_secure_storage`, certificate pinning, `Random.secure()`, `formz` validation, dependency vulnerability scanning with `osv-scanner`, and OWASP Mobile Top 10 guidance |
4040
| [**License Compliance**](skills/license-compliance/SKILL.md) | Dependency license auditing — categorizes licenses (permissive, weak/strong copyleft, unknown), flags non-compliant or missing licenses, and produces a structured compliance report using Very Good CLI |
41+
| [**Dart/Flutter SDK Upgrade**](skills/dart-flutter-sdk-upgrade/SKILL.md) | Bump Dart and Flutter SDK constraints across packages — CI workflow versions, pubspec.yaml environment constraints, and PR preparation for SDK upgrades |
4142

4243
## Hooks
4344

@@ -76,6 +77,7 @@ You can also invoke skills directly as slash commands:
7677
/vgv-static-security
7778
/vgv-testing
7879
/vgv-license-compliance
80+
/vgv-dart-flutter-sdk-upgrade
7981
```
8082

8183
## What Each Skill Provides

‎skills/dart-flutter-sdk-upgrade/SKILL.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
---
2+
name: vgv-dart-flutter-sdk-upgrade
3+
description: >
4+
VGV-specific reference for bumping Dart and Flutter SDK constraints across packages.
5+
Use when upgrading the Flutter or Dart SDK version in any VGV repository — bumping
6+
pubspec.yaml environment constraints, updating CI workflow Flutter versions, or preparing
7+
an SDK upgrade PR. CI uses ^MAJOR.MINOR.x to resolve to the latest patch; pubspec pins
8+
the exact patch version (e.g., ^3.50.1). Trigger on phrases like "bump Flutter to 3.x",
9+
"update SDK constraints", "upgrade Dart SDK", "update CI Flutter version",
10+
"bump SDK version", or "prep the SDK upgrade PR".
11+
allowed-tools: Read,Glob,Grep,Edit,Write,Bash
12+
---
13+
14+
# VGV Flutter/Dart SDK Upgrade — Quick Reference
15+
16+
One PR per project. Only CI workflow and `pubspec.yaml` changes — no logic, no dependency
17+
version bumps, no test changes.
18+
19+
---
20+
21+
## Core Standards
22+
23+
Apply these standards to ALL SDK upgrade work:
24+
25+
- **Flutter and Dart versions differ** — always look up the Dart version bundled with the target Flutter release from https://docs.flutter.dev/install/archive
26+
- **CI uses `^MAJOR.MINOR.x`** — wildcard patch so CI always gets the latest patch
27+
- **pubspec pins exact patch** — use `^MAJOR.MINOR.PATCH` with the specific patch version
28+
- **Pure Dart packages** — use the Dart version directly, no Flutter mapping needed
29+
- **Verify with `pub get` and `analyze`** — don't silently resolve conflicts
30+
31+
---
32+
33+
## 0. Resolve target version
34+
35+
Flutter bundles a specific Dart release — their version numbers do **not** match. For
36+
example, Flutter 3.41.0 ships with Dart 3.11.0. You must look up the correct Dart version
37+
for the target Flutter release before editing any files.
38+
39+
**How to find the Dart version:**
40+
41+
1. Open https://docs.flutter.dev/install/archive
42+
2. Find the target Flutter stable release
43+
3. Note the Dart version listed alongside it
44+
45+
If the user has not specified a Flutter version, look up the latest Flutter stable release
46+
from that same page. For pure Dart packages (no Flutter dependency), the Dart version is
47+
whatever the user specifies or the latest stable — no Flutter mapping needed.
48+
49+
Confirm both resolved versions with the user before editing files.
50+
51+
---
52+
53+
## 1. CI workflows — `.github/workflows/`
54+
55+
VGV packages use `VeryGoodOpenSource/very_good_workflows` reusable workflows. Leave the
56+
`@v1` tag untouched. Use `^MAJOR.MINOR.x` — caret with literal `x` as the patch wildcard
57+
so CI always resolves to the latest release patch automatically. When bumping versions,
58+
update MAJOR and/or MINOR as appropriate (e.g., `^3.41.x` → `^3.42.x` or `^4.0.x`):
59+
60+
**Flutter package:**
61+
62+
```yaml
63+
uses: VeryGoodOpenSource/very_good_workflows/.github/workflows/flutter_package.yml@v1
64+
with:
65+
flutter_version: "^3.41.x" # ← caret + MAJOR.MINOR.x, resolves to latest patch
66+
```
67+
68+
**Pure Dart package** — note the key is `dart_sdk`, not `flutter_version`. Use the Dart
69+
version, not the Flutter version:
70+
71+
```yaml
72+
uses: VeryGoodOpenSource/very_good_workflows/.github/workflows/dart_package.yml@v1
73+
with:
74+
dart_sdk: "^3.11.x" # ← Dart version (not Flutter version)
75+
```
76+
77+
If a file uses `flutter_channel: stable` instead of a pinned version,
78+
pin the version — VGV always pins Flutter versions in CI workflows.
79+
80+
---
81+
82+
## 2. `pubspec.yaml` environment constraints
83+
84+
Format is `^MAJOR.MINOR.PATCH` (caret, exact patch). Unlike CI, pubspec pins a specific
85+
patch version — the one the user specifies or the current stable at the time of the bump.
86+
87+
**Flutter package** (has `flutter:` under `dependencies`):
88+
89+
```yaml
90+
environment:
91+
sdk: ^3.11.0 # ← Dart version bundled with the target Flutter release
92+
flutter: ^3.41.0 # ← Flutter version
93+
```
94+
95+
**Pure Dart package** (no Flutter SDK dependency):
96+
97+
```yaml
98+
environment:
99+
sdk: ^3.11.0 # ← Dart version only
100+
# no flutter: line
101+
```
102+
103+
In a monorepo, update each package's `pubspec.yaml` individually. The shared CI workflow
104+
only needs updating once.
105+
106+
---
107+
108+
## 3. Verify
109+
110+
Run from each package directory. **Use Dart/Flutter MCP tools if available; otherwise Bash.**
111+
112+
```bash
113+
flutter pub get # or: dart pub get (for pure Dart packages)
114+
flutter analyze # or: dart analyze
115+
```
116+
117+
If `pub get` fails with dependency conflicts, report them — don't silently resolve by
118+
upgrading packages. If `analyze` surfaces new errors introduced by the SDK bump, report
119+
them rather than fixing them in this PR.
120+
121+
---
122+
123+
## 4. PR scope check
124+
125+
Before committing, confirm the diff contains only:
126+
127+
- `.github/workflows/*.yml`
128+
- `pubspec.yaml` (one or more)
129+
130+
```bash
131+
git diff HEAD --name-only
132+
```
133+
134+
Suggested commit/PR message:
135+
136+
```
137+
chore: bump Flutter to 3.41.0 / Dart to 3.11.0
138+
139+
- Update flutter_version in .github/workflows/ to ^3.41.x (CI resolves latest patch)
140+
- Update environment sdk/flutter constraints in pubspec.yaml
141+
142+
No logic or code changes.
143+
```

‎skills/very-good-analysis-upgrade/SKILL.md‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
---
2+
name: vgv-very-good-analysis-upgrade
3+
description: Upgrade very_good_analysis lint package to new version across Dart/Flutter projects. Handles version bump, lint fixes, and PR creation.
4+
allowed-tools: Read,Glob,Grep,Bash
5+
---
6+
7+
# Upgrade very_good_analysis
8+
9+
This skill guides the full upgrade of `very_good_analysis` in a Dart or Flutter project.
10+
The goal is a clean, focused PR: nothing more than the version bump in `pubspec.yaml` plus
11+
the minimal code changes needed to satisfy any new lint rules introduced in that version.
12+
13+
---
14+
15+
## Core Standards
16+
17+
These standards apply to every `very_good_analysis` upgrade.
18+
19+
- **Keep the PR focused** — include only the version bump and required lint fixes
20+
- **Fix only new warnings** — do not address pre-existing issues in the same PR
21+
- **Avoid behavior changes** — if a lint fix alters runtime behavior, flag it for review
22+
- **Verify with analysis** — end with a clean `flutter analyze` or `dart analyze`
23+
24+
---
25+
26+
## Before You Start
27+
28+
Confirm two things before proceeding:
29+
30+
1. **Target version** — if the user didn't specify a version, fetch the latest from the pub.dev API
31+
and use that. Don't ask — just look it up and proceed:
32+
33+
```bash
34+
curl -s https://pub.dev/api/packages/very_good_analysis | jq -r '.latest.version'
35+
```
36+
37+
Tell the user which version you're upgrading to before making any changes.
38+
39+
2. **Project scope** — is this a single package or a monorepo? In a monorepo, each sub-package
40+
with its own `pubspec.yaml` needs its own bump (and potentially its own PR).
41+
42+
---
43+
44+
## Step 1 — Bump the version in pubspec.yaml
45+
46+
Locate the `pubspec.yaml` file(s) for the project. Update the `very_good_analysis` entry under
47+
`dev_dependencies`:
48+
49+
```yaml
50+
dev_dependencies:
51+
very_good_analysis: ^x.y.z # replace x.y.z with the target version
52+
```
53+
54+
Keep the caret (`^`) prefix — that's the VGV convention. Don't change anything else in the file.
55+
56+
After editing, run:
57+
58+
```bash
59+
flutter pub get
60+
```
61+
62+
(For a pure Dart package without Flutter, use `dart pub get` instead.)
63+
64+
Use the Dart/Flutter MCP server if it is connected and exposes pub commands; otherwise run via Bash.
65+
66+
---
67+
68+
## Step 2 — Run flutter analyze
69+
70+
```bash
71+
flutter analyze
72+
```
73+
74+
Or for a pure Dart package:
75+
76+
```bash
77+
dart analyze
78+
```
79+
80+
Capture the full output. You're looking for new warnings or errors introduced by the version bump —
81+
lints that weren't flagged before. Ignore pre-existing issues unrelated to the bump (don't fix
82+
things that were already broken; that belongs in a separate PR).
83+
84+
---
85+
86+
## Step 3 — Fix the lint warnings
87+
88+
Work through the warnings one by one. Keep fixes **minimal and lint-compliance-only**:
89+
90+
- Fix only what `flutter analyze` flags
91+
- Don't refactor, rename, or reorganize anything beyond what's needed
92+
- Don't fix pre-existing lint warnings that existed before the bump
93+
- If a warning looks like it might require a behavioral change (not just style), flag it for
94+
human review rather than silently fixing it
95+
96+
After fixing, re-run `flutter analyze` to confirm zero warnings remain.
97+
98+
---
99+
100+
## Step 4 — Verify the fix is complete
101+
102+
Run the full analyze pass one more time to make sure nothing was missed:
103+
104+
```bash
105+
flutter analyze
106+
```
107+
108+
Expected output: `No issues found!` (or only pre-existing issues that you haven't touched).
109+
110+
If new warnings appear that weren't there after Step 2, address them now. If warnings persist
111+
after multiple attempts, list them explicitly and ask the user how they'd like to proceed.
112+
113+
---
114+
115+
## Step 5 — Create the PR
116+
117+
Stage only the changed files:
118+
119+
```bash
120+
git add pubspec.yaml pubspec.lock # always include these
121+
# plus any .dart files you edited for lint fixes
122+
```
123+
124+
Commit with a clear message following the project's conventions. A good default:
125+
126+
```
127+
chore: upgrade very_good_analysis to x.y.z
128+
129+
Bump very_good_analysis from <old> to <new> and resolve
130+
lint warnings introduced by newly enabled rules.
131+
```
132+
133+
Then push and open a PR. The PR should contain **nothing else** — no feature work, no unrelated
134+
refactors, no extra cleanup. Reviewers should be able to see at a glance that this is purely
135+
a lint compliance update.
136+
137+
If the project uses a PR template, fill it in. Mention specifically which rules were newly
138+
enabled if any warnings required code changes.
139+
140+
---
141+
142+
## Tips and edge cases
143+
144+
**Monorepos**: Each package that depends on `very_good_analysis` needs its own `pubspec.yaml`
145+
bump. You can often run `flutter analyze` from the repo root to surface all warnings at once,
146+
but `pub get` must be run per-package.
147+
148+
**analysis_options.yaml**: `very_good_analysis` ships its own `analysis_options.yaml` that is
149+
included by the project's own options file. You generally don't need to touch the project's
150+
`analysis_options.yaml` — the bump in `pubspec.yaml` is sufficient to pull in the new rules.
151+
152+
**Breaking rule changes**: Occasionally a new version disables a rule that was previously
153+
enabled, or changes its severity. That might cause previously-flagged issues to disappear,
154+
which is fine — don't re-introduce them.
155+
156+
**flutter pub get fails**: If dependency resolution fails after the bump (version conflicts),
157+
investigate the conflict before proceeding. Don't force-upgrade other dependencies just to
158+
make the bump work — surface the conflict to the user.
159+
160+
---
161+
162+
## Additional Resources
163+
164+
See [reference.md](reference.md) for a quick-reference table of common lint rules introduced by `very_good_analysis` upgrades and their typical fixes (`prefer_const_constructors`, `use_super_parameters`, `unnecessary_late`, `avoid_dynamic_calls`, `require_trailing_commas`, `unnecessary_null_checks`).

‎skills/very-good-analysis-upgrade/reference.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Upgrade very_good_analysis — Reference
2+
3+
Extended examples and common lint rule fixes for the very_good_analysis upgrade skill.
4+
5+
---
6+
7+
## Common Lint Rule Fixes
8+
9+
| Lint rule | Typical fix |
10+
| --------------------------- | ---------------------------------------------------- |
11+
| `prefer_const_constructors` | Add `const` keyword |
12+
| `use_super_parameters` | Convert `super.param` to initializer |
13+
| `unnecessary_late` | Remove `late` from immediately-initialized variables |
14+
| `avoid_dynamic_calls` | Cast the receiver to a specific type |
15+
| `require_trailing_commas` | Add trailing comma in argument/parameter lists |
16+
| `unnecessary_null_checks` | Remove redundant `!` operators |

0 commit comments

Comments
 (0)