From a4a33a0503260f70b7d6d03022649db90eb2ace6 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 12 Sep 2026 05:34:35 +0000 Subject: [PATCH 1/6] docs: document --flutter-version=fvm and =system Documents the two `--flutter-version` aliases that let Shorebird follow the Flutter version you already use, and makes clear that Shorebird still builds with its own fork at that version rather than your fvm or system Flutter install. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01SQV4ay9pqj2NUBhw72dLW8 --- .../docs/getting-started/flutter-version.mdx | 26 +++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/src/content/docs/getting-started/flutter-version.mdx b/src/content/docs/getting-started/flutter-version.mdx index c8d7dbfa..ec4f3706 100644 --- a/src/content/docs/getting-started/flutter-version.mdx +++ b/src/content/docs/getting-started/flutter-version.mdx @@ -106,6 +106,32 @@ always be built with the version of Flutter used by the release. ::: +### Match the Flutter version you already use + +If you manage Flutter with [fvm](https://fvm.app), or you just want Shorebird to +follow the `flutter` on your `PATH`, `--flutter-version` accepts two aliases so +you don't have to repeat the version number: + +```sh +# Use the version fvm resolves for this project (from its .fvmrc). +shorebird release android --flutter-version=fvm + +# Use the version reported by the `flutter` on your PATH. +shorebird release android --flutter-version=system +``` + +Shorebird asks that Flutter which version it is, then builds with Shorebird's +fork of Flutter at the same version. It does not build with your fvm or system +Flutter install, so the usual rules still apply: the version has to be one +Shorebird supports, and patches are built with the version used by the release. + +:::note + +`--flutter-version=fvm` requires `fvm` on your `PATH`, and runs +`fvm flutter --version` from your project directory to resolve the version. + +::: + ### Flutter version notes To help you avoid hidden pitfalls, Shorebird maintains version notes on Flutter From 20893b96f6d53607b087508fb0b6ae4f8f266e9e Mon Sep 17 00:00:00 2001 From: Abhishek Doshi Date: Fri, 18 Sep 2026 14:01:20 +0530 Subject: [PATCH 2/6] chore: add fvmrc to the cspell dictionary The new fvm section in flutter-version.mdx references `.fvmrc`, which failed the spell-check job. `fvm` itself already passes via the shared allowed dictionary; only `fvmrc` needs adding. --- .cspell.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/.cspell.yaml b/.cspell.yaml index 00b68b96..431311b0 100644 --- a/.cspell.yaml +++ b/.cspell.yaml @@ -53,6 +53,7 @@ words: - ffigen - fintech - frontmatter + - fvmrc - gallego - gles - graphql From 9c5f727ad6d022f88d2f73829505a3f36813a327 Mon Sep 17 00:00:00 2001 From: Abhishek Doshi Date: Fri, 18 Sep 2026 14:04:24 +0530 Subject: [PATCH 3/6] fix: capitalize Code Push in how-to-install-flutter Vale's Terms rule requires "Code Push". The occurrence spans a line break, which older Vale releases did not join, so it only started failing when the vale-action picked up a newer Vale: the same main commit (9796712) passed style-check on 2026-09-17 and failed on 2026-09-18. This is a main-branch failure inherited by this branch when main was merged in, not something this PR introduced. --- src/content/docs/flutter-concepts/how-to-install-flutter.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/flutter-concepts/how-to-install-flutter.mdx b/src/content/docs/flutter-concepts/how-to-install-flutter.mdx index d0ea7d5b..61fe2446 100644 --- a/src/content/docs/flutter-concepts/how-to-install-flutter.mdx +++ b/src/content/docs/flutter-concepts/how-to-install-flutter.mdx @@ -339,8 +339,8 @@ iwr -UseBasicParsing 'https://raw.githubusercontent.com/shorebirdtech/install/ma Shorebird installs to `~/.shorebird/bin` and automatically adds itself to PATH. It also installs a private copy of Flutter inside -`~/.shorebird/bin/cache/flutter`, this is Shorebird's modified Flutter for code -push and should **not** be added to your PATH. The total installation size is +`~/.shorebird/bin/cache/flutter`, this is Shorebird's modified Flutter for Code +Push and should **not** be added to your PATH. The total installation size is approximately **300 MB**. You can verify the installation by running this: From c6e0f9e646ce6bbd94e88e0d9c516c387c4f2549 Mon Sep 17 00:00:00 2001 From: Abhishek Doshi Date: Fri, 18 Sep 2026 14:07:01 +0530 Subject: [PATCH 4/6] Revert "fix: capitalize Code Push in how-to-install-flutter" This reverts commit 9c5f727ad6d022f88d2f73829505a3f36813a327. --- src/content/docs/flutter-concepts/how-to-install-flutter.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/flutter-concepts/how-to-install-flutter.mdx b/src/content/docs/flutter-concepts/how-to-install-flutter.mdx index 61fe2446..d0ea7d5b 100644 --- a/src/content/docs/flutter-concepts/how-to-install-flutter.mdx +++ b/src/content/docs/flutter-concepts/how-to-install-flutter.mdx @@ -339,8 +339,8 @@ iwr -UseBasicParsing 'https://raw.githubusercontent.com/shorebirdtech/install/ma Shorebird installs to `~/.shorebird/bin` and automatically adds itself to PATH. It also installs a private copy of Flutter inside -`~/.shorebird/bin/cache/flutter`, this is Shorebird's modified Flutter for Code -Push and should **not** be added to your PATH. The total installation size is +`~/.shorebird/bin/cache/flutter`, this is Shorebird's modified Flutter for code +push and should **not** be added to your PATH. The total installation size is approximately **300 MB**. You can verify the installation by running this: From 0912a3663c0f822012cd814cfc27e78bf635d68e Mon Sep 17 00:00:00 2001 From: Abhishek Doshi Date: Wed, 23 Sep 2026 13:04:46 +0530 Subject: [PATCH 5/6] docs: correct how --flutter-version=fvm resolves, and note =system's PATH requirement - fvm asks fvm's JSON API for the project's pin first; fvm flutter --version is only the fallback for a channel or fork ref pin, and it may install Flutter first. - =system needs flutter on PATH, which a Shorebird-only user won't have. - Note the minimum Shorebird version (1.6.123). --- .../docs/getting-started/flutter-version.mdx | 27 ++++++++++++------- 1 file changed, 18 insertions(+), 9 deletions(-) diff --git a/src/content/docs/getting-started/flutter-version.mdx b/src/content/docs/getting-started/flutter-version.mdx index ec4f3706..3fdaf9b6 100644 --- a/src/content/docs/getting-started/flutter-version.mdx +++ b/src/content/docs/getting-started/flutter-version.mdx @@ -108,9 +108,10 @@ always be built with the version of Flutter used by the release. ### Match the Flutter version you already use -If you manage Flutter with [fvm](https://fvm.app), or you just want Shorebird to -follow the `flutter` on your `PATH`, `--flutter-version` accepts two aliases so -you don't have to repeat the version number: +As of Shorebird 1.6.123, if you manage Flutter with [fvm](https://fvm.app), or +you just want Shorebird to follow the `flutter` on your `PATH`, +`--flutter-version` accepts two aliases so you don't have to repeat the version +number: ```sh # Use the version fvm resolves for this project (from its .fvmrc). @@ -120,15 +121,23 @@ shorebird release android --flutter-version=fvm shorebird release android --flutter-version=system ``` -Shorebird asks that Flutter which version it is, then builds with Shorebird's -fork of Flutter at the same version. It does not build with your fvm or system -Flutter install, so the usual rules still apply: the version has to be one -Shorebird supports, and patches are built with the version used by the release. +Shorebird resolves the alias to a version number, then builds with Shorebird's +fork of Flutter at that version. It does not build with your fvm or system +Flutter install, so the version still has to be one Shorebird supports. :::note -`--flutter-version=fvm` requires `fvm` on your `PATH`, and runs -`fvm flutter --version` from your project directory to resolve the version. +`--flutter-version=fvm` requires `fvm` on your `PATH`. Shorebird first asks fvm +what your project pins in its `.fvmrc`. If that pin is a version number, the +answer comes back immediately. If it's a channel like `stable`, or a fork ref, +Shorebird falls back to running `fvm flutter --version`, which may have to +install that Flutter first and can take several minutes. + +`--flutter-version=system` requires `flutter` on your `PATH`. If Shorebird is +your only Flutter install, you won't have one: Shorebird's private copy lives in +`~/.shorebird/bin/cache/flutter` and +[should not be added to your PATH](/flutter-concepts/how-to-install-flutter). +Pass an explicit version number instead. ::: From e91ec7b456a29e450651018e8f6459d0984ea2b9 Mon Sep 17 00:00:00 2001 From: Abhishek Doshi Date: Wed, 23 Sep 2026 13:14:00 +0530 Subject: [PATCH 6/6] docs: show the version Shorebird resolved the alias to --- src/content/docs/getting-started/flutter-version.mdx | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/src/content/docs/getting-started/flutter-version.mdx b/src/content/docs/getting-started/flutter-version.mdx index 3fdaf9b6..3d0b2a43 100644 --- a/src/content/docs/getting-started/flutter-version.mdx +++ b/src/content/docs/getting-started/flutter-version.mdx @@ -125,6 +125,13 @@ Shorebird resolves the alias to a version number, then builds with Shorebird's fork of Flutter at that version. It does not build with your fvm or system Flutter install, so the version still has to be one Shorebird supports. +Shorebird prints the version it resolved before it starts building, so you can +check it against the one you expected: + +```sh +Using Flutter %flutter_version%, as reported by `fvm`. +``` + :::note `--flutter-version=fvm` requires `fvm` on your `PATH`. Shorebird first asks fvm