Skip to content

docs: document --flutter-version=fvm and =system #661

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
eseidel wants to merge 6 commits into
base: main
Choose a base branch
from
+27 −0
Open

docs: document --flutter-version=fvm and =system #661

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
a4a33a0
docs: document --flutter-version=fvm and =system
claude Sep 12, 2026
02ddf2a
Merge branch 'main' into claude/kind-dirac-pyzrkq
AbhishekDoshi26 Sep 18, 2026
20893b9
chore: add fvmrc to the cspell dictionary
AbhishekDoshi26 Sep 18, 2026
9c5f727
fix: capitalize Code Push in how-to-install-flutter
AbhishekDoshi26 Sep 18, 2026
c6e0f9e
Revert "fix: capitalize Code Push in how-to-install-flutter"
AbhishekDoshi26 Sep 18, 2026
df19b21
Merge branch 'main' into claude/kind-dirac-pyzrkq
AbhishekDoshi26 Sep 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .cspell.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,7 @@ words:
- ffigen
- fintech
- frontmatter
- fvmrc
- gallego
- gles
- graphql
Expand Down
26 changes: 26 additions & 0 deletions src/content/docs/getting-started/flutter-version.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,6 +106,32 @@ always be built with the version of Flutter used by the release.

:::

### Match the Flutter version you already use

@AbhishekDoshi26 AbhishekDoshi26 Sep 18, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Optional, and only relevant once this is unblocked: it may be worth a sentence noting that these aliases need a CLI that has them.

Everything else on this page works on any recent CLI, so a reader on v1.6.122 who hits Version fvm not found has no way to tell from the page that their CLI is simply too old. A short "requires Shorebird vX.Y.Z or later" line, filled in once the release ships, would close that gap. The version table above sets the precedent for that style.


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.

@AbhishekDoshi26 AbhishekDoshi26 Sep 18, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: the :::note about 20 lines above already says "Patches will always be built with the version of Flutter used by the release." This sentence is carrying it a second time.

Fix: trim the tail so the sentence ends on the point unique to this section:

Flutter install, so the usual rules still apply: the version has to be one
Shorebird supports.


:::note

`--flutter-version=fvm` requires `fvm` on your `PATH`, and runs

@AbhishekDoshi26 AbhishekDoshi26 Sep 18, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This describes the fallback, not the normal path, and it leaves out the part users will actually notice.

What getFvmVersion() does in the merged #3932:

  1. Runs fvm api project --path <root> first. Its comment is explicit that this "reads the project's .fvmrc without touching the Flutter install, so it answers immediately and can't trigger a download."
  2. If the pinned value matches ^\d+\.\d+\.\d+$, it returns right there. fvm flutter --version never runs. This is the common case, a project pinned to a version number.
  3. fvm flutter --version runs only when the project pins a channel (stable) or a fork ref, or when fvm is too old to have an api command.

Why it matters: step 3 is the expensive path. From the implementation comment, "That can install Flutter first, which is slow and prints nothing while it runs, so we say what we're waiting on." The CLI prints a progress message specifically because of this. Someone whose .fvmrc pins stable will sit through a silent multi-minute Flutter download, and right now the docs give no warning while describing that slow path as normal.

Fix:

:::note

`--flutter-version=fvm` requires `fvm` on your `PATH`. Shorebird asks fvm for the
version your project pins, which it reads from `.fvmrc` without running Flutter.

If your project pins a channel (like `stable`) or a fork instead of a version
number, Shorebird has to ask that Flutter which version it is, which means fvm
may download and install it first. That can take several minutes the first time.

:::

`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
Expand Down
Loading