Upgrade deliberately in a separate working copy or branch. A source constraint such as ^3.12.2 defines allowed Dart versions; it is not a promise that every new Flutter/toolchain combination has been tested.
Record the currently working Flutter/Dart versions and keep pubspec.yaml, pubspec.lock, and native project files. Run the existing app checks before changing versions so you can distinguish new failures from old ones.
Treat Riverpod annotations and generator packages as a coordinated set. Also check Freezed, JSON serialization, build runner, Firebase plugins, and native platform requirements together. Avoid pre-release packages for a normal production update.
Use flutter pub outdated to inspect available versions. Review the official package changelogs and constraints before editing dependencies. Do not begin by running an unrestricted major-version upgrade across the whole project.
Resolve dependencies, regenerate affected code, and run analysis/tests and both platform builds as appropriate:
Test release behavior on devices, particularly secure storage, session refresh, PDFs, signing, and notification registration. Preserve the new lockfile only after validation.
If compatibility is uncertain, keep the documented release toolchain and request clarification before introducing the upgrade into a customer production build.