flutter/shorebird
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs: Remove most TRUSTED_TESTER.md contents

Browse Source 
These are all now covered by docs.shorebird.dev
This commit is contained in:
Eric Seidel
2023-04-26 17:07:13 -07:00
committed by GitHub
parent bfb8c267ef
commit 02e5f2d074
1 changed files with 2 additions and 488 deletions
Download Patch File Download Diff File Expand all files Collapse all files
TRUSTED_TESTERS.md
+2 -488
View File
@@ -1,492 +1,6 @@
# Trusted Testers
https://docs.shorebird.dev/ is now our official docs!
We're in the process of replacing this document with https://docs.shorebird.dev/
please try our new docs site and let us know if we've missed anything!
While this document is public, access to Shorebird services are not yet
generally available. We're running a trusted tester program with a limited
number of users to ensure that we're building the right thing and that it's
stable for general use.
If you'd like to be a part of the program, please fill out this form:
https://forms.gle/T7x5h5bb6bMBB7hUA
## Welcome!
If you're joining the trusted tester program, welcome! Thank you for your help
making Shorebird a reality.
## Our goal
Our goal with this Trusted Tester program is to shake out bugs and ensure that
we are building things people want. We _want_ your feedback. We _want_ you to
break things. We _want_ you to tell us what you want to see next. We're
already a default-public company, but we intend to be even more open with you
and will be shipping your regular updates during the program, responding to
your feedback.
Filing [issues](https://github.com/shorebirdtech/shorebird/issues) is a good way
to provide feedback. Feedback via Discord is also welcome.
Our guiding principle for these early days is "first, do no harm".
It should be the case that using Shorebird is never worse than not using Shorebird.
It is still possible using early versions of Shorebird could break your app in
the wild. If you believe that's the case, please reach out, we're here to help.
## What works today
You can build and deploy new (release) versions of your app to all Android
users via `shorebird` command line from a Mac or Linux host.
All users will synchronously update to the new version on next launch
(no control over this behavior yet,
[issue](https://github.com/shorebirdtech/shorebird/issues/127)).
Basic access to the updater through package:dart_bindings (unpublished).
https://github.com/shorebirdtech/shorebird/tree/main/updater/dart_bindings
Shorebird command line can show a list of what apps and app versions you've
associated with your account and what patches you've pushed to those apps.
https://github.com/shorebirdtech/shorebird/tree/main/packages/shorebird_cli
## What doesn't yet
No support for:
- Windows hosts ([issue](https://github.com/shorebirdtech/shorebird/issues/37))
- Teams / Organizations sharing apps [issue](https://github.com/shorebirdtech/shorebird/issues/345)
- Flutter channels (only latest stable 3.7.12 is supported)
- Rollbacks ([issue](https://github.com/shorebirdtech/shorebird/issues/126))
- Staged rollout of patches (channels or percentage based) [issue](https://github.com/shorebirdtech/shorebird/issues/110)
- Async updates / downloads [issue](https://github.com/shorebirdtech/shorebird/issues/123)
- Analytics
- Web interface
- CI/CD (GitHub Actions, etc.) integration
- Patch signing [issue](https://github.com/shorebirdtech/shorebird/issues/112)
- Asset changes (images, icons, etc.) [issue](https://github.com/shorebirdtech/shorebird/issues/318)
- Plugin changes (java, kotlin, etc.) -- currently only supports changing Dart code.
## Installing Shorebird command line
Install the `shorebird` command-line tool by running the following command:
```bash
curl --proto '=https' --tlsv1.2 https://raw.githubusercontent.com/shorebirdtech/install/main/install.sh -sSf | sh
```
This installs `shorebird` into `~/.shorebird/bin` and adds it to your path.
It also installs a copy of Flutter and Dart inside `~/.shorebird/bin/cache/flutter`.
These versions are not intended to be used for development (yet), you can
continue to use the versions of Flutter and Dart you already have installed.
The total install is about 300mb.
More information: https://github.com/shorebirdtech/install/blob/main/README.md
## Creating your Shorebird account
Once you have Shorebird installed, you need to create a Shorebird account.
Currently Shorebird uses Google OAuth to authenticate users. If you need other
auth methods, please [let us
know](https://github.com/shorebirdtech/shorebird/issues/335).
```bash
shorebird account create
```
Will prompt you with a Google OAuth link. Once you've authenticated, it will
create your Shorebird account for you.
## Subscribing to Shorebird Trusted Tester program
Once you have a Shorebird account, you need to subscribe to the Trusted Tester
program. This will give you access to the Shorebird services.
The cost during the Trusted Tester program is $20 USD per user per month. There
is currently no limit on the number of apps you can release or update during
the trusted tester program. We currently only support Android apps built from a
Mac or Linux host.
```bash
shorebird account subscribe
```
This command will give you a link to Stripe where you can complete your subscription.
Once the payment is complete, you'll have access to the rest of Shorebird.
We strongly recommend you [join us on
Discord](https://discord.com/invite/9hKJcWGcaB) so that we can provide you live
support. Once you've subscribed, you can message Eric on Discord and he can add
you to the #trusted-testers private channel.
## Using Shorebird code push
If you already have a Flutter app, you can build it with Shorebird in a few steps:
1. If you did not just create your account above, you may need to login.
`shorebird login` will prompt you to refresh your OAuth token if it's
expired.
2. Once you're logged in, you can use `shorebird init`. This needs to be run
within the directory of your Flutter app, it reads and writes your `pubspec.yaml`
and will write out a new `shorebird.yaml` file.
`shorebird init` does three things:
1. Tells Shorebird that your app exists (e.g. so it can hold patches to it
and vend them to devices when asked).
2. Creates a `shorebird.yaml` file to your project. `shorebird.yaml` contains
the app_id for your app, which is the unique identifier the app will send to
Shorebird servers to identify which application to pull updates for.
3. Finally, `shorebird init` also adds the `shorebird.yaml` to the assets
section of your `pubspec.yaml` file, ensuring `shorebird.yaml` is bundled
into your app's assets.
You can go ahead and commit these changes, they will be innocuous even if you
don't end up using Shorebird with this application.
If you don't want to try this on your main application yet, any Flutter app,
including the default Flutter counter works too, e.g.
```
% flutter create shorebird_test
% cd shorebird_test
% shorebird init
? How should we refer to this app? (shorebird_test) shorebird_test
✓ Initialized Shorebird (38ms)
🐦 Shorebird initialized successfully!
✅ A shorebird app has been created.
✅ A "shorebird.yaml" has been created.
✅ The "pubspec.yaml" has been updated to include "shorebird.yaml" as an asset.
Reference the following commands to get started:
🚙 To run your project use: "shorebird run".
📦 To create a new release use: "shorebird release".
🚀 To push an update use: "shorebird patch".
For more information about Shorebird, visit https://shorebird.dev
```
3. Typical development usage will involve normal `flutter` commands. Only
when you go to build the final release version of your app, do you need to use
the `shorebird` command-line tool.
## Permissions needed for Shorebird
Shorebird code push requires the Network permission to be added to your
`AndroidManifest.xml` file. (Which in Flutter is located in
`android/app/src/main/AndroidManifest.xml`.) This is required for the
app to be able to communicate with the Shorebird servers to pull new patches.
```xml
<manifest ...>
<uses-permission android:name="android.permission.INTERNET" />
...
</manifest>
```
Running `shorebird doctor` will check that your `AndroidManifest.xml` file
is set up correctly.
## Shorebird's fork of Flutter
`shorebird` uses a fork of Flutter that includes the Shorebird updater.
This fork is currently based on Flutter 3.7.12.
We replace a few of the Flutter engine files with our own. To do that, we use
`FLUTTER_STORAGE_BASE_URL` to point to download.shorebird.dev instead of
download.flutter.dev. We pass through unmodified output from the `flutter`
tool so you will see a warning from Flutter:
```
Flutter assets will be downloaded from http://download.shorebird.dev. Make sure you trust this source!
```
For more information about why we had to fork Flutter see:
[FORKING_FLUTTER.md](FORKING_FLUTTER.md).
## Running your Shorebird-built app
You can use `shorebird run` to build and run your app on a connected
Android device. This is similar to `flutter run --release` just with
Shorebird's fork of the Flutter engine that includes the Shorebird updater.
`shorebird run` wraps `flutter run` and can take any argument `flutter run` can.
To pass arguments to the underlying `flutter run` use a `--` separator. For example:
`shorebird run -- -d my_device` will run on a specific device.
During this trusted tester period, you will likely see several logs from the
shorebird updater. These are for debugging in case you have trouble
and will be removed/silenced in future iterations.
Example:
```
% shorebird run
Running app...
Using hardware rendering with device sdk phone64 arm64. If you notice graphics artifacts, consider enabling software rendering with "--enable-software-rendering".
Launching lib/main.dart on sdk phone64 arm64 in release mode...
Running Gradle task 'assembleRelease'...
17.6s
✓ Built build/app/outputs/flutter-apk/app-release.apk (8.5MB).
Installing build/app/outputs/flutter-apk/app-release.apk...
375ms
Flutter run key commands.
h List all available interactive commands.
c Clear the screen
q Quit (terminate the application on the device).
W/FlutterJNI( 7283): shorebird.yaml: app_id: 4f636c95-f859-4de3-a730-dde1c099cd53
D/flutter ( 7283): updater::logging: Logging initialized
I/flutter ( 7283): updater::config: Updater configured with: ResolvedConfig { is_initialized: true, cache_dir: "/data/user/0/com.example.test_counter/code_cache/shorebird_updater", download_dir: "/data/user/0/com.example.test_counter/code_cache/shorebird_updater/downloads", channel: "stable", app_id: "4f636c95-f859-4de3-a730-dde1c099cd53", release_version: "1.0.0", original_libapp_path: "libapp.so", vm_path: "libflutter.so", base_url: "https://api.shorebird.dev" }
I/flutter ( 7283): [INFO:flutter_main.cc(108)] Starting Shorebird update
W/flutter ( 7283): updater::cache: Failed to load updater state: No such file or directory (os error 2)
I/flutter ( 7283): updater::network: Sending patch check request: PatchCheckRequest { app_id: "4f636c95-f859-4de3-a730-dde1c099cd53", channel: "stable", release_version: "1.0.0", patch_number: None, platform: "android", arch: "aarch64" }
D/flutter ( 7283): reqwest::connect: starting new connection: https://api.shorebird.dev/
E/flutter ( 7283): updater::updater: Problem updating: error sending request for url (https://api.shorebird.dev/api/v1/patches/check): error trying to connect: dns error: failed to lookup address information: No address associated with hostname
E/flutter ( 7283): updater::updater: disabled backtrace
W/flutter ( 7283): updater::cache: Failed to load updater state: No such file or directory (os error 2)
E/flutter ( 7283): [ERROR:flutter/shell/platform/android/flutter_main.cc(127)] Shorebird updater: no active path.
```
If you see messages like
```
E/flutter ( 7283): updater::updater: Problem updating: error sending request for url (https://api.shorebird.dev/api/v1/patches/check): error trying to connect: dns error: failed to lookup address information: No address associated with hostname
```
That indicates you have not yet added the network permissions (see above)
to your app, as I had forgotten when running my example above.
## Creating a release
Before you can start uploading patches, you will need to create a release.
Creating a release builds and submits your app to Shorebird. Shorebird saves the
compiled Dart code from your application in order to make patches smaller in
size.
Example:
```
% shorebird release
✓ Building release (5.1s)
✓ Fetching apps (0.2s)
What is the version of this release? (1.0.0) 1.0.0
🚀 Ready to create a new release!
📱 App: My App (30370f27-dbf1-4673-8b20-fb096e38dffa)
📦 Release Version: 1.0.0
🕹️ Platform: android (arm64, arm32, x86)
Would you like to continue? (y/N) Yes
✓ Fetching releases (55ms)
✓ Creating release (45ms)
✓ Creating artifacts (4.6s)
✅ Published Release!
Your next step is to upload the app bundle to the Play Store.
./build/app/outputs/bundle/release/app-release.aab
See the following link for more information:
https://support.google.com/googleplay/android-developer/answer/9859152?hl=en
```
## Publishing patches to your app
To publish a patch to your app, use `shorebird patch`. It should look like:
```
% shorebird patch
✓ Building patch (16.2s)
✓ Fetching apps (0.1s)
Which release is this patch for? (0.1.0) 0.1.0
🚀 Ready to publish a new patch!
📱 App: My App (61fc9c16)
📦 Release Version: 0.1.0
📺 Channel: stable
🕹️ Platform: android (arm64, arm32, x86)
Would you like to continue? (y/N) Yes
✓ Fetching release (41ms)
✓ Fetching release artifacts (43ms)
✓ Downloading release artifacts (0.2s)
✓ Creating artifacts (0.3s)
✓ Uploading artifacts (43ms)
✓ Fetching channels (40ms)
✓ Promoting patch to stable (43ms)
✅ Published Patch!
```
This will generate a new patch for your app and upload it to the Shorebird
servers for distribution to all other copies of your app. For example, you could
try `shorebird run` to run and install your app, and then stop it. Make edits
and `shorebird patch` and then run the app again directly (by clicking on it,
without using `shorebird run`) and you should notice that it updates to the
latest built and published version rather than using the previously installed
version.
The current `shorebird patch` flow is not how we envision Shorebird being used
longer term (e.g one might push a git hash to a CI/CD system, which would then
publish it to Shorebird). However, it's the simplest thing to do for now.
Note that you can only publish a patch to an app that you have already told
shorebird about. This is normally done by `shorebird init` followed by
`shorebird release`. If needed you can also create an app via
`shorebird apps create` and modify the `shorebird.yaml` directly yourself, see:
https://github.com/shorebirdtech/shorebird/tree/main/packages/shorebird_cli#create-app
Your applications in the wild will query for updates with their `app_id` (which
comes from `shorebird.yaml`) and their release version (which comes from
AndroidManifest.xml, which in turn is generated from pubspec.yaml).
## Building a release version of your app
You can use `shorebird build` to build a release version of your app including
the Shorebird updater.
`shorebird build` wraps `flutter build` and can take any argument `flutter build`
can. To pass arguments to the underlying `flutter build` you need
to put `flutter build` arguments _after_ a `--` separator. For example:
`shorebird build -- --dart-define="foo=bar"` will define the "foo" environment
variable inside Dart as you might have done with `flutter build` directly.
Success should look like this:
```
% shorebird build appbundle
✓ Building shorebird engine (8.0s)
✓ Building release (6.4s)
```
## Passing additional arguments to build commands
The `shorebird` command uses `flutter` to do the actual building. For example:
when you call `shorebird build appbundle` it calls `flutter build appbundle`.
If you need to pass additional arguments to `flutter build` you can do so
by adding a `--` after the `shorebird` arguments before any additional
`flutter` arguments, for example:
`shorebird build appbundle -- --no-tree-shake-icons` will pass
`--no-tree-shake-icons` to the underlying `flutter build appbundle` command.
This also works with `shorebird run`, `shorebird release` and `shorebird patch`
to pass additional arguments to `flutter`. Overtime we intend to expose
more of these arguments directly on `shorebird` just haven't yet. If you
have any you need, please file an issue and we're happy to fix!
This passthrough behavior is also the only way to specify a device at this time:
`shorebird run -- -d my_device`
https://github.com/shorebirdtech/shorebird/issues/331
## Update behavior
The Shorebird updater is currently hard-coded to update synchronously on
launch. This means that when you push a new version of your app, all users
will update on next launch.
https://github.com/shorebirdtech/shorebird/issues/166
We expect to add more control over update behavior in the future, including
supporting asynchronous updates and percentage based rollout. Please let us know
if these are important to you and we are happy to prioritize them!
The Shorebird updater is designed such that when the network is not available,
or the server is down or otherwise unreachable, the app will continue to run
as normal. Should you ever choose to delete an update from our servers, all your
clients will continue to run as normal.
We have not yet added the ability to rollback patches, but it's on our todo
list and happy to prioritize it if it's important to you. For now, the simplest
thing is to simply push a new patch that reverts the changes you want to undo.
## Play Store
Although Shorebird connects to the network, it does not send any personally
identifiable information. Including Shorebird should not affect your
declarations for the Play Store.
Requests sent from the app to Shorebird servers include:
- app_id (specified `shorebird.yaml`)
- channel (optional in `shorebird.yaml`)
- release_version (versionName from AndroidManifest.xml)
- patch_number (generated as part of `shorebird patch`)
- arch (e.g. 'aarch64', needed to send down the right patch)
- platform (e.g. 'android', needed to send down the right patch)
That's it. The code for this is in `updater/library/src/network.rs`
## Play Store Guidelines
Shorebird is designed to be compatible with the Play Store guidelines. However
Shorebird is a tool, and as with any tool, can be abused. Deliberately abusing
Shorebird to violate Play Store guidelines is in violation of the Shorebird
[Terms of Service](shorebird.dev/terms.html) and can result in termination of
your account.
Examples of guidelines you should be aware of, include "Deceptive Behavior" and
"Unwanted Software". Please be clear with your users about what you are
providing with your application and do not violate their expectations with
significant behavioral changes through the use of Shorebird.
Code push services are widely used in the industry (all of the large apps
I'm aware of use them) and there are multiple other code push services
publicly available (e.g. expo.dev & appcenter.ms). This is a well trodden path.
## What about iOS?
Current Shorebird is Android-only. We have plans to add iOS, but not yet
implemented. Using Shorebird for your Android builds does not affect
your iOS builds. You can successfully ship a Shorebird-built appbundle
to Google Play and continue to ship a Flutter-built ipa to the App Store.
The difference will be that you will be able to update your Android users
sooner than you will your iOS users for now.
## Disabling Shorebird
_First, do no harm_
Shorebird is designed to be a drop-in replacement for the stock Flutter engine,
and can be disabled at any time with no effect on your users.
Building with `shorebird build` will include Shorebird code push in your app.
Building with `flutter build --release` will not include Shorebird in your app.
At any time you can simply drop back to `flutter build` and things will work
as they did before.
We have not yet added the ability to delete your account from Shorebird from
the command line, however reach out to us via Discord or email and we are
happy to help you immediately delete your account and disable all updates
for your app(s) deployed with Shorebird. We anticipate adding this ability
to the command line in the near future.
You can remove `shorebird` from your path by removing it from your `.bashrc` or
`.zshrc` and deleting the `.shorebird` directory located in `~/.shorebird`.
Keeping this link alive for a few days while we fix inbound links.
# Release Notes