Skip to content

Commit 115ac17

Browse files
eseidelfelangel
eseidel
and
felangel
authored
docs: add more docs from shorebird repo (#15)
* docs: Add more docs copied from shorebird repo I'm not sure we actually need all of these. I did modify them some to make more sense. But I suspect we will need another pass to clean these up. * Now with 100% more formatting * Update docs/faq.md * Update docs/faq.md --------- Co-authored-by: Felix Angelov <[email protected]>
1 parent e0af925 commit 115ac17

File tree

6 files changed

+293
-2
lines changed

6 files changed

+293
-2
lines changed

‎docs/architecture.md

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
---
2+
sidebar_position: 5
3+
title: 🏛️ Architecture
4+
description: How Shorebird works.
5+
---
6+
7+
## Overview
8+
9+
Shorebird is a set of tools that allow you to build and deploy new versions of
10+
your Flutter app directly to your users' devices.
11+
12+
Shorebird consists of 3 major parts:
13+
14+
- A command line tool that you use to build and deploy your app.
15+
- A modified Flutter engine that you include in your app.
16+
- Servers that host patches for your app.
17+
18+
## `shorebird` tool
19+
20+
The `shorebird` tool is documented extensively elsewhere. Most of the build
21+
logic is just wrapping the `flutter` tool and it also adds a few commands to
22+
interface with Shorebird's servers.
23+
24+
## A modified Flutter engine
25+
26+
Code push requires technical changes to the underlying Flutter engine. To make
27+
those changes required forking Flutter.
28+
29+
We had to fork 3 Flutter repos to make Shorebird work:
30+
31+
### flutter/engine
32+
33+
The engine is the C++ code that runs on the device. It is responsible for
34+
rendering the UI, handling input, and communicating with the host.
35+
36+
We forked this code to add the ability to have release versions of the Flutter
37+
engine be able to load new code from Shorebird's servers.
38+
39+
At time of writing, Shorebird's fork is based on Flutter 3.7.12. You can see
40+
our engine changes here:
41+
https://github.com/flutter/engine/compare/3.7.12...shorebirdtech:engine:stable_codepush
42+
43+
### flutter/flutter
44+
45+
The flutter/flutter repo contains the Dart code that runs on the device as well
46+
as the `flutter` tool that is used to build and run Flutter apps.
47+
48+
We initially did not fork this code. And still don't really want to fork
49+
this code, but in order to deliver a modified engine without affecting other
50+
Flutter installations, we needed to be able to change the _version_ of the
51+
engine that the `flutter` tool downloads.
52+
53+
Our one fork is to change bin/internal/engine.version to point to our
54+
engine version. You can see our changes here:
55+
https://github.com/flutter/flutter/compare/3.7.8...shorebirdtech:flutter:stable_codepush
56+
57+
### flutter/buildroot
58+
59+
The buildroot repo contains the build scripts that are used to build the
60+
Flutter engine for various platforms. It's separate from flutter/engine in
61+
order to share code and configuration with the Fuchsia build system.
62+
63+
We also didn't want to fork this code. However we need to for now in order
64+
to integrate our updater code. Our updater code:
65+
https://github.com/shorebirdtech/updater
66+
is a Rust library which we link into the engine. The way we do that is via
67+
a C-API on a static library (libupdater.a). The default flags for linking
68+
for the Flutter engine hide all symbols from linked static libraries. We
69+
need to be able to expose the shorebird\_\* symbols from libupdater.a up through
70+
FFI to the Dart code. We did that my making one change to buildroot and then
71+
a second change to the engine to place the symbols on the allow-list.
72+
73+
Our one change:
74+
https://github.com/shorebirdtech/buildroot/commit/7383548fa2306b5d53979ac5e9d176b35258811b
75+
76+
## Vendoring our fork
77+
78+
When you install Shorebird, it installs Flutter and Dart from our fork. These
79+
are currently not exposed on the user's path, rather just private copies
80+
that Shorebird will use when building your app.
81+
82+
This was necessary to avoid conflicts with other Flutter installations on the
83+
user's machine. Specifically, the way that Flutter downloads artifacts is
84+
based on the version of the engine. If we were to use the same version of the
85+
engine as the user's Flutter installation, then we would overwrite the user's
86+
engine artifacts.
87+
88+
We deliver our artifacts to this fork of Flutter with two ways. First is we
89+
change the version of the engine in the `flutter` tool. Second is we pass
90+
FLUTTER_STORAGE_BASE_URL set to download.shorebird.dev (instead of
91+
download.flutter.io) when calling our vended copy of the `flutter` tool.
92+
93+
Currently this means `shorebird` will not work in an environment where the
94+
user needs to use FLUTTER_STORAGE_BASE_URL to download Flutter artifacts
95+
from a private mirror (e.g. a corporate network or China).
96+
https://github.com/shorebirdtech/shorebird/issues/237
97+
98+
## Serving our forked binaries
99+
100+
We also use a custom server to handle requests from `flutter` for our
101+
(modified) engine. You can see that server here:
102+
https://github.com/shorebirdtech/shorebird/tree/main/packages/artifact_proxy
103+
104+
Our "artifact_proxy" knows how to serve the modified binaries from our
105+
Google Storage bucket, as well as how to serve unmodified binaries for all
106+
parts of Flutter we didn't have to modify from
107+
Google's Flutter Google storage bucket.

‎docs/faq.md

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
---
2+
sidebar_position: 4
3+
title: ❓ FAQ
4+
description: Frequently asked questions.
5+
---
6+
7+
## How does Shorebird relate to Flutter?
8+
9+
Shorebird is a fork of Flutter that adds code push. Shorebird is not a
10+
replacement for Flutter, but rather a replacement for the Flutter engine. You
11+
can continue to use the Flutter tooling you already know and love.
12+
13+
`shorebird` uses a fork of Flutter that includes the Shorebird updater. We track
14+
the latest stable release of Flutter and replace a few of the Flutter engine
15+
files with our modified copies.
16+
17+
To implement our fork, we use `FLUTTER_STORAGE_BASE_URL` to point to
18+
`https://download.shorebird.dev` instead of download.flutter.dev. We pass
19+
through unmodified output from the `flutter` tool so you will see a warning from
20+
Flutter:
21+
22+
```
23+
Flutter assets will be downloaded from http://download.shorebird.dev. Make sure you trust this source!
24+
```
25+
26+
For more information about why we had to fork Flutter see
27+
[architecture.md](architecture.md).
28+
29+
## When do updates happen?
30+
31+
Shorebird udpater is currently hard-coded to run on app startup. It runs on
32+
a background thread and does not block the UI thread. Any updates will be
33+
installed while the user is using the app and will be applied the next time the
34+
app is restarted.
35+
36+
The Shorebird updater is designed such that when the network is not available,
37+
or the server is down or otherwise unreachable, the app will continue to run
38+
as normal. Should you ever choose to delete an update from our servers, all your
39+
clients will continue to run as normal.
40+
41+
We have not yet added the ability to rollback patches. For now, the simplest
42+
thing is to simply push a new patch that reverts the changes you want to undo.
43+
44+
We expect to add more control over update behavior in the future. Please let us
45+
know if you have needs here, and we're happy to prioritize them.
46+
47+
## What information is sent to Shorebird servers?
48+
49+
Although Shorebird connects to the network, it does not send any personally
50+
identifiable information. Including Shorebird should not affect your
51+
declarations for the Play Store.
52+
53+
Requests sent from the app to Shorebird servers include:
54+
55+
- app_id (specified `shorebird.yaml`)
56+
- channel (optional in `shorebird.yaml`)
57+
- release_version (versionName from AndroidManifest.xml)
58+
- patch_number (generated as part of `shorebird patch`)
59+
- arch (e.g. 'aarch64', needed to send down the right patch)
60+
- platform (e.g. 'android', needed to send down the right patch)
61+
That's it. The code for this is in `updater/library/src/network.rs`
62+
63+
## Does Shorebird comply with Play Store guidelines?
64+
65+
Shorebird is designed to be compatible with the Play Store guidelines. However
66+
Shorebird is a tool, and as with any tool, can be abused. Deliberately abusing
67+
Shorebird to violate Play Store guidelines is in violation of the Shorebird
68+
[Terms of Service](https://shorebird.dev/terms) and can result in termination of
69+
your account.
70+
71+
Examples of guidelines you should be aware of, include "Deceptive Behavior" and
72+
"Unwanted Software". Please be clear with your users about what you are
73+
providing with your application and do not violate their expectations with
74+
significant behavioral changes through the use of Shorebird.
75+
76+
Code push services are widely used in the industry (all of the large apps
77+
I'm aware of use them) and there are multiple other code push services
78+
publicly available (e.g. expo.dev & appcenter.ms). This is a well trodden path.
79+
80+
## What platforms does Shorebird support? Does it support iOS?
81+
82+
Current Shorebird is Android-only. We have plans to add iOS, but not yet
83+
implemented. Using Shorebird for your Android builds does not affect
84+
your iOS builds. You can successfully ship an appbundle build with `shorebird`
85+
to Google Play and an ipa built with `flutter` to the App Store.
86+
The difference will be that you will be able to update your Android users
87+
sooner than you will your iOS users for now.
88+
89+
We've focused on Android so far on the assumption that most Flutter developers
90+
are targeting Android first. Shorebird can (relatively easily) be made to
91+
support Desktop or embedded targets. If those are important to you, please let
92+
us know.

‎docs/status.md

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
sidebar_position: 3
3+
title: 👷 Status
4+
description: Status of the Shorebird project.
5+
---
6+
7+
## Open Beta
8+
9+
Shorebird is currently "Open Beta". A lot is still changing, but we're
10+
ready and interested for feedback from the general public.
11+
12+
Our goal with this open beta is to shake out bugs and ensure that
13+
we are building things people want. We _want_ your feedback. We _want_ you to
14+
break things. We _want_ you to tell us what you want to see next.
15+
16+
Filing [issues](https://github.com/shorebirdtech/shorebird/issues) is a good way
17+
to provide feedback. Feedback via Discord is also welcome.
18+
19+
Our guiding principle for these early days is "first, do no harm".
20+
It should be the case that using Shorebird is never worse than not using Shorebird.
21+
It is still possible using early versions of Shorebird could break your app in
22+
the wild. If you believe that's the case, please reach out, we're here to help.
23+
24+
## What works today
25+
26+
You can build and deploy new (release) versions of your app to all Android
27+
users via `shorebird` command line.
28+
29+
All users will update to the new version on next launch in the background
30+
(no control over this behavior yet).
31+
32+
We also have an extensive command line interface for managing your Shorebird
33+
account and apps.
34+
35+
## What doesn't work?
36+
37+
No support for:
38+
39+
- Teams / Organizations sharing apps [issue](https://github.com/shorebirdtech/shorebird/issues/345)
40+
- Flutter channels (only latest stable 3.7.12 is supported)
41+
- Rollbacks ([issue](https://github.com/shorebirdtech/shorebird/issues/126))
42+
- Staged rollout of patches (channels or percentage based) [issue](https://github.com/shorebirdtech/shorebird/issues/110)
43+
- Async updates / downloads [issue](https://github.com/shorebirdtech/shorebird/issues/123)
44+
- Analytics
45+
- Web interface
46+
- CI/CD (GitHub Actions, etc.) integration
47+
- Patch signing [issue](https://github.com/shorebirdtech/shorebird/issues/112)
48+
- Asset changes (images, icons, etc.) [issue](https://github.com/shorebirdtech/shorebird/issues/318)
49+
- Plugin changes (java, kotlin, etc.) -- not planned.
50+
- iOS [issue](https://github.com/shorebirdtech/shorebird/issues/381)
51+
52+
If these, or anything else is blocking your use of Shorebird, please let us know!
53+
https://github.com/shorebirdtech/shorebird/issues

‎docs/uninstall.md

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
---
2+
sidebar_position: 6
3+
title: 🛑 Uninstall
4+
description: How to disable Shorebird.
5+
---
6+
7+
_First, do no harm_
8+
9+
Shorebird is designed to be a drop-in replacement for stock Flutter,
10+
and can be disabled at any time with no effect on your users.
11+
12+
## Thank you
13+
14+
Thank you for trying Shorebird. If you'd like to continue using Shorebird
15+
but have questions or concerns, please reach out to us on Discord or
16+
via email at [[email protected]](mailto:[email protected]).
17+
18+
Otherwise, we hope you'll consider trying Shorebird again in the future.
19+
20+
## Canceling your subscription
21+
22+
To cancel your subscription:
23+
24+
`shorebird account cancel`
25+
26+
This will cancel your subscription. Your access (and updates for your users)
27+
will continue until the end of the current billing period. After which
28+
shorebird will not longer send updates to your apps, but your apps will
29+
continue function otherwise normally.
30+
31+
## Uninstalling Shorebird
32+
33+
Building with `shorebird build` will include Shorebird code push in your app.
34+
Building with `flutter build --release` will not include Shorebird in your app.
35+
At any time you can simply drop back to `flutter build` and things will work
36+
as they did before.
37+
38+
You can remove `shorebird` from your path by removing it from your `.bashrc` or
39+
`.zshrc` and deleting the `.shorebird` directory located in `~/.shorebird`.

‎package-lock.json

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@
3232
"@docusaurus/module-type-aliases": "^2.4.0",
3333
"@tsconfig/docusaurus": "^1.0.7",
3434
"eslint": "^8.36.0",
35-
"prettier": "^2.8.5",
35+
"prettier": "^2.8.8",
3636
"typescript": "^5.0.2"
3737
},
3838
"browserslist": {

0 commit comments

Comments
 (0)