diff --git a/docs/concepts.md b/docs/concepts.md index 887f7675..b49b72f0 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -8,6 +8,40 @@ description: Concepts used in Shorebird's code push product An explanation of the concepts used in Shorebird's code push product. +## Code Push + +Code push, also referred to as "over the air updates" (OTA) is a cloud service +enabling Flutter developers to deploy updates to their apps in production. +Shorebird currently works on Android and iOS (alpha) and will eventually work +everywhere Flutter works. + +"Code Push" is a reference to the name of a deploy feature used by the React +Native community from [Microsoft](https://appcenter.ms) and +[Expo](https://expo.dev), neither of which support Flutter. + +## Patching + +Patching is the process of updating an application's code without requiring the +user to download a new version from the App Store or Play Store. This is done by +creating a patch, which is a set of changes to the application's code that can +be applied over-the-air. + +### What types of changes can be included in a patch? + +Patches can change any Dart code in your application. This includes: + +- App code +- Generated code +- Dependencies in `pubspec.yaml`, as long as they don't include native code + changes. + +This does **not** include: + +- Asset files (images, fonts, etc.), although we have plans to support this in + the near future (see https://github.com/shorebirdtech/shorebird/issues/318). +- Native code (e.g. Java/Kotlin on Android or Objective-C/Swift on iOS). +- Flutter engine changes (i.e., changes the Flutter version of your app). + ## Glossary ### Application diff --git a/docs/faq.md b/docs/faq.md index 0971ab02..ee2c9e20 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -7,17 +7,6 @@ description: Frequently asked questions. If you have questions not answered here, please ask! Both filing an issue or asking on [Discord](https://discord.gg/shorebird)) work. -### What is "code push"? - -Code push, also referred to as "over the air updates" (OTA) is a cloud service -enabling Flutter developers to deploy updates to their apps in production. -Shorebird currently works on Android and iOS (alpha) and will eventually work -everywhere Flutter works. - -"Code Push" is a reference to the name of a deploy feature used by the React -Native community from [Microsoft](https://appcenter.ms) and -[Expo](https://expo.dev), neither of which support Flutter. - ### What is the difference between a patch and a release? We use the term "release" to mean preparing a binary for the app stores. In @@ -196,8 +185,9 @@ for you, please let us know! ### Does code push work with large applications? Yes. There is no limit on the size of the application that can be patched with -code push. As noted [below](#what-types-of-changes-does-shorebird-code-push-support), -Shorebird can change any Dart code in your application no matter of size. +code push. As noted in +[Concepts](concepts#what-types-of-changes-can-be-included-in-a-patch), Shorebird +can change any Dart code in your application no matter of size. ### What can I use Shorebird code push for? @@ -271,22 +261,6 @@ production. We will use a variety of different techniques to make this possible depending on the platform. Current demos execute ahead-of-time compiled Dart code and do not require a JIT Dart compiler. -### What types of changes does Shorebird code push support? - -Shorebird can change any Dart code in your application. This includes app code -and generated code. You can also update dependencies in `pubspec.yaml` as long -as they don't require native code changes. - -We have plans to support changing Flutter asset files (from pubspec.yaml) in the -near future: https://github.com/shorebirdtech/shorebird/issues/318 - -We do not have plans to support changing native code (e.g. Java/Kotlin on -Android or Objective-C/Swift on iOS), and the tool will warn you if it detects -that you have changed native code as it will not be included in the patch. - -Shorebird also cannot change your app's Flutter version in a patch, as the -Flutter engine is native code. - ### Does Shorebird support Flutter Web? Code push isn't needed for Flutter web. When a user opens a web app it downloads diff --git a/docs/update-strategies.md b/docs/update-strategies.md index 1fdfe369..3512d076 100644 --- a/docs/update-strategies.md +++ b/docs/update-strategies.md @@ -82,8 +82,7 @@ necessary patch and _not_ then prompt them to update. Shorebird patches are typically much smaller than full app downloads (a few KB on Android, a few hundred KB on iOS), so it is likely better for your users if you can use Shorebird to deliver patches instead of `in_app_update`. However, -there are [changes which Shorebird cannot -make](faq#what-types-of-changes-does-shorebird-code-push-support), so +there are [changes which Shorebird cannot make](concepts#what-types-of-changes-can-be-included-in-a-patch), so `in_app_update` may be the best solution in some cases. Shorebird "patches" also do not change the version number of your app, so