Anatomy of a Flutter upgrade.

Introduction

A lot of things happen in the lifecycle of an app. Bugs get fixed and features are added. Besides the changes in functionality of the app itself, it is also important to maintain and upgrade the dependencies of the app. Once in a while you have to upgrade the Flutter version that you are using. Upgrading the Flutter version is what this document is all about.

Upgrading Flutter

I think that everybody who uses Flutter has seen this message once in a while:

┌─────────────────────────────────────────────────────────────────────────────┐
│ A new version of Flutter is available!                                      │
│                                                                             │
│ To upgrade to the latest version, run "flutter upgrade".                    │
└─────────────────────────────────────────────────────────────────────────────┘

This command only updates the Flutter tooling, it does nothing for your source code. Although it looks that this is harmless, there is a caveat. Your project now contains files and folders that were generated with an older version of Flutter while it is compiled with a newer Flutter version.

Some examples:

• .gitignore might have changed and you might track or ignore wrong files and folders.

• The platform folders might have changes. Think about a new gradle version being used by the latest version of Flutter (build.gradle => build.gradle.kts).

• There might be new or changed entries in the pubspec.yaml.

Upgrading Flutter and your project step-by-step

The solution I describe in this document is to create all files and folders with the latest version of Flutter and to merge back the necessary changes. On top of that git is used to document the upgrade step-by step. For installing an pinning specific Flutter versions to a project, I use fvm.

You can use this git repository alongside with this document.

https://github.com/jsroest/upgrade_demo/commits/main/

Step 01 - Step 06: Create sample app

With “Step 01” through “Step 06” I created a demo app with Flutter 3.29.3 for demonstrating the upgrade process. As these steps are not relevant for the upgrade process itself, I do not describe the details here.

Step 07: Start flutter upgrade from 3.29.3 to 3.32.4.

This is an empty commit that documents the start of the update process.

Step 08: Delete all except .git, lib and test.

Delete everything except the source in the lib and test folder. Be sure to also delete all hidden files, except the “.git” folder. Add a commit to document the deletion.

Step 09: Create a new project with Flutter 3.32.4.

To minimize the manual work, it is necessary to use the same values with the “Flutter create” command as that was used in the original project.

• Match the description of the project.

• Match the organization.

• Match the project name.

• Match all platforms used and their languages (Java/Kotlin Objective-C/Swift).

• etc

Make 3.32.4 global and check the version fvm is using afterwards.

• fvm global 3.32.4

• fvm flutter --version

Recreate all files except any files in the lib and test folder. Flutter will skip those folders if they are already present.

• fvm flutter create --description "Demo upgrade from flutter 3.29.3 to flutter 3.32.4" --org com.rubigo --project-name upgrade_demo --platforms android .

• git add .

Add a commit to document the newly created files.

Step 10: Pin to Flutter 3.32.4 with fvm.

Pin the version of Flutter to use with fvm.

• fvm use 3.32.4

• git add .

Add a commit to document the new Flutter version to use for this project.

Step 11: Start manual merge.

This is the most complicated part of the upgrade. Here you have to judge the changes you have made to the original files and you have to merge them with the newly created files and or structure.

I like to mark this with an empty commit, to just have a point you can rollback to if the merge fails.

After the empty commit you have to do the following:

• Delete all except .git (don’t forget the hidden files and folders).

• Get all files and folders from Step 07. For this you have to know the git commit hash that belongs to Step 07.
  git checkout e019a0d144027d849bfb87f664ee5f0946bccde8 -- .
  This command will copy all files and folders that are present at the moment of Step 07.

• After the checkout you have to judge and merge every single file manually.

  I find Android Studio a good tool for that, because it’s easy to

  • Rollback a file if you want to keep the newly generated one.

  • Revert changes per line or block.

  • Commit the changes per file.

If you make a mistake with merging a specific file, you will have to restore the original from Step 07 with:
git checkout e019a0d144027d849bfb87f664ee5f0946bccde8 -- path/to/file

• I like to commit the changes per file.
  Be aware that it can be very confusing.

  Old version: Is the newly generated file.

  New version: Is the original file from Step 07.

Step 12: Merge completed. Flutter upgrade to 3.32.4 done.

I prefer an empty commit to mark the merge and upgrade as completed.

When you are done, you can check the upgrade by selecting the commit of Step 12 and Step 07. For that you can use e.g. Sourcetree or Fork

Final words

There is more work to be done after this. The code you have now may not compile at this point.

You might have to do one or more from these steps:

• Update/check all dependencies

• Migrate abandoned/unmaintained packages

• Apply new code guidelines and or lints

• Reformat all your code

Let me know what you think, feedback is appreciated.