Release a module once for every host app
A Flutter module’s release version is the module’s own version. You pick it when
you release the module, and devices report it from whatever host app runs that
build of the module. One shorebird release aar or
shorebird release ios-framework, and the patches you make to it, reach every
host app that embeds that build, at every host app version:
- A host app can bump its version or ship a new store release without a new module release, and its users keep getting your patches.
- A module embedded in several host apps is released once and patched once.
This needs Shorebird 1.6.142 or newer with Flutter 3.47.9 or newer. Patch these
releases with Shorebird 1.6.142 or newer too: an older Shorebird sees the
release_version built into the module’s shorebird.yaml as a changed asset,
and stops in CI. For modules built on older versions, see
Modules built on older versions.
Pick a release version
Section titled “Pick a release version”Pass the module’s version as --release-version when you release it:
- Each module build needs a release version that platform hasn’t used yet, as with any release. An Android and an iOS build can share one, as above, if they’re built with the same Flutter version.
- It doesn’t depend on the host app’s version. Any scheme works, such as the
versionin your module’spubspec.yamlor a CI build number. Use ASCII letters, digits,.,_,+and-, up to 128 characters. While devices still run host app builds that embed a module built on older versions, pick versions that can’t equal one of those host app versions, for example with a prefix such asm2.4.0+1: those devices report the host app’s version, so they’d be offered this release’s patches, which can’t install on their build. - On Android,
--build-numbersets only the version of theaarin its Maven repository, which the host app’sbuild.gradlenames. It never reaches devices. Pass the same--build-numbertoshorebird patch aaras to the release. If you publish theaarto Maven, you may want it to match the release version.
Patch a release with the same release version:
To check that a module carries its own version, look at the patch check line in
the device logs: release_version is the module’s
version, and host_version shows the host app’s when they differ. If you
released with a version that differs from the host app’s and the line still
shows the host app’s version as release_version, with no host_version, the
host app isn’t running a module build made with Shorebird 1.6.142 and Flutter
3.47.9 or newer; see
Modules built on older versions.
Which host apps get a patch
Section titled “Which host apps get a patch”Each host app embeds a module build from a module release’s release directory,
as the Android and
iOS guides describe. A host app gets the
patches of the module release it embeds:
- When you release a new module build, a host app gets that release’s patches once it ships the new build. A host app that still ships an older build gets only the older release’s patches. To fix a bug in both, patch both releases.
- A patch reaches every host app that embeds the release and checks the patch’s
track, and a rollback reaches all of them: Shorebird doesn’t choose patches by
host app. To try a patch in one host app first, give that host app’s QA build
its own track, as QA builds does.
Store builds keep checking
stable.
Your existing CI keeps working
Section titled “Your existing CI keeps working”If your CI passes the host app’s version as --release-version, as older
versions required, it keeps working:
shorebird releasebuilds with the Flutter version your Shorebird version pins unless you pass--flutter-version, so upgrading Shorebird to 1.6.142 also builds the module with Flutter 3.47.9. Devices then report the release version you passed, which still equals the host app’s version, so they get the same patches as before, as long as each host app embeds the module build released for it. To give the module its own versions, pass one at your next module release.- If you build with an older Flutter through
--flutter-version(a version,systemorfvm), or with theflutter-versioninput of theshorebird-releaseGitHub Action, the module can’t carry its own version, and devices report the host app’s version as before.
Three cases need a change:
- If a host app build embeds a module build from a different release (an earlier
one, or one released under another host app’s version, such as the latest
aarboth host apps pull from Maven), its devices report that release’s version and get only its patches. Build each host app from thereleasedirectory of the module release made for it, or release the module once for all of them and patch that release. - Shorebird 1.6.142 and newer accept a module’s
--release-versiononly if it uses ASCII letters, digits,.,_,+and-, up to 128 characters. If the host app’s version uses anything else, such as a space inversionName, pass a module version of your own instead, and build the module with Flutter 3.47.9 or newer: a module built with an older Flutter reports the host app’s version, so a version of your own gets no patches. - Patch with Shorebird 1.6.142 or newer too. A patch job on an older Shorebird
sees the
release_versionthe release built intoshorebird.yamlas a changed asset, and stops in CI.
Modules built on older versions
Section titled “Modules built on older versions”A module built with Shorebird older than 1.6.142 or Flutter older than 3.47.9
can’t carry its own version. Devices report the host app’s version instead, so
--release-version must equal it:
- Android:
versionName+versionCodefrom the host app’sapp/build.gradle. - iOS:
CFBundleShortVersionString+CFBundleVersionfrom the host app’sInfo.plist.
Each new host app version then needs a new module release before its users get patches.
Shorebird 1.6.142 and newer accept a module’s --release-version only if it
uses ASCII letters, digits, ., _, + and -, up to 128 characters, so the
host app’s version has to fit that rule too.
What devices send
Section titled “What devices send”Besides the module’s release version, Android and iOS releases built with
Flutter 3.47.9 or newer send the host app’s package name or bundle ID, as
host_bundle_id, with each patch check and patch event. A module whose release
version differs from the host app’s version also sends the host app’s version,
as host_version. See
What Shorebird Collects.