diff --git a/src/content/docs/account/api-keys.mdx b/src/content/docs/account/api-keys.mdx index 66eb9d7a..ffd66c60 100644 --- a/src/content/docs/account/api-keys.mdx +++ b/src/content/docs/account/api-keys.mdx @@ -39,7 +39,7 @@ export SHOREBIRD_TOKEN="" shorebird patch android ``` -For platform-specific setup, see our CI guides for +For platform-specific setup, see the CI guides for [GitHub Actions](/code-push/ci/github/), [Codemagic](/code-push/ci/codemagic/), or the [generic CI guide](/code-push/ci/generic/). @@ -73,8 +73,8 @@ action cannot be undone. ## Migrating from `shorebird login:ci` The `shorebird login:ci` command is deprecated. Existing tokens generated by -`login:ci` will continue to work until September 2026, but we recommend -replacing them with API keys created from the console. +`login:ci` will continue to work until September 2026, but replacing them with +API keys created from the console is recommended. To migrate: diff --git a/src/content/docs/account/billing.mdx b/src/content/docs/account/billing.mdx index 148f2455..342b7b0e 100644 --- a/src/content/docs/account/billing.mdx +++ b/src/content/docs/account/billing.mdx @@ -10,15 +10,15 @@ import viewBillingPortal from '~/assets/view_billing_portal.png'; import accountMonthlySpendingLimit from '~/assets/account_monthly_spending_limit.png'; import setSpendingLimitDialog from '~/assets/set_spending_limit_dialog.png'; -We believe billing should never be a blocker to using our tools. We aim to meet -our customers where they are, whether that means flexible payment methods, -enterprise invoicing, or custom terms. If you’re building with Flutter, we want -to make it as easy as possible to build with Shorebird too. +Billing should never be a blocker to using Shorebird's tools. Customers are met +where they are, whether that means flexible payment methods, enterprise +invoicing, or custom terms. If you’re building with Flutter, building with +Shorebird should be just as easy. ## Payment provider - Stripe -Shorebird uses Stripe for all billing and payments. We accept any payment method -that Stripe supports. You can view more details in +Shorebird uses Stripe for all billing and payments, and accepts any payment +method that Stripe supports. You can view more details in [Stripe's Supported Payment Methods documentation](https://docs.stripe.com/payments/payment-methods/overview). ### Billing email @@ -42,15 +42,15 @@ which is where invoices are sent. ## Available plans -We provide flexible options to accommodate every team and product, whether it's -an indie/hobby project or a globally launched enterprise application. See our -[pricing page](https://shorebird.dev/pricing) for more information. +Flexible options are provided to accommodate every team and product, whether +it's an indie/hobby project or a globally launched enterprise application. See +the [pricing page](https://shorebird.dev/pricing) for more information. -Most customers can easily get started with our self-service Pro and Business +Most customers can easily get started with the self-service Pro and Business plans. If you need invoice billing, tax support, alternative payment methods, custom contract/procurement process, or support for more than 2.5 million patches per month, please -[reach out to us regarding an Enterprise Plan](https://shorebird.dev/talk-to-sales). +[reach out regarding an Enterprise Plan](https://shorebird.dev/talk-to-sales). ### Organizations & billing @@ -79,13 +79,13 @@ Console. These numbers are updated hourly. ### Overage billing -For our monthly plans, we offer optional overage billing. This is turned off by +For monthly plans, optional overage billing is available. This is turned off by default. Customers can control their spending limits in the [Shorebird Console](https://console.shorebird.dev). Your spending limit defaults -to the price of your plan. We'll notify you via email once when you’re close to -your limit, and again when you’ve reached your limit. +to the price of your plan. You'll be notified via email once when you’re close +to your limit, and again when you’ve reached your limit. -If you do not use these providers, we've also provided generic instructions -below: +If you do not use these providers, generic instructions are provided below: ## Installing Shorebird @@ -50,10 +49,10 @@ for more details, see [Getting Started](/). -Now that you have a token, it is important to keep that token secure. We -recommend using a secrets manager for the token, or secure environment -variables, depending on your CI setup. `shorebird` commands will look for the -token to be in a `SHOREBIRD_TOKEN` environment variable. +Now that you have a token, it is important to keep that token secure. Using a +secrets manager for the token, or secure environment variables, is recommended, +depending on your CI setup. `shorebird` commands will look for the token to be +in a `SHOREBIRD_TOKEN` environment variable. ## Replacing `flutter build --release` with `shorebird`. @@ -115,8 +114,8 @@ used to build the release and use that exact version to build the patch. ## CI best practices -When integrating Shorebird into a continuous integration pipeline, we recommend -following these best practices to ensure reliable and efficient builds: +When integrating Shorebird into a continuous integration pipeline, following +these best practices is recommended to ensure reliable and efficient builds: ### Pin the Flutter version for releases @@ -185,4 +184,4 @@ bypass interactive prompts in other environments, you can pass the `--no-confirm` flag to `shorebird patch` or `shorebird release`. Thank you for reading this guide. If you have any questions or suggestions, feel -free to reach out to us at our [Discord](https://discord.gg/shorebird). +free to reach out on [Discord](https://discord.gg/shorebird). diff --git a/src/content/docs/code-push/ci/github.mdx b/src/content/docs/code-push/ci/github.mdx index 6c5915fc..65805869 100644 --- a/src/content/docs/code-push/ci/github.mdx +++ b/src/content/docs/code-push/ci/github.mdx @@ -57,9 +57,8 @@ jobs: run: shorebird --version ``` -In the above workflow, we're using the `setup-shorebird` action to configure -Shorebird in our CI and in subsequent steps we can execute any Shorebird -commands. +In the above workflow, the `setup-shorebird` action is used to configure +Shorebird in CI, and subsequent steps can execute any Shorebird commands. {/* prettier-ignore */} :::note @@ -85,7 +84,7 @@ name: SHOREBIRD_TOKEN secret: ``` -Now we can use the `SHOREBIRD_TOKEN` in our GitHub workflow to perform +Now the `SHOREBIRD_TOKEN` can be used in the GitHub workflow to perform authenticated functions such as creating patches 🎉 ## Create releases @@ -212,7 +211,7 @@ The `shorebird-patch` action also outputs the patch number: ::: -For an example of a fully automated development workflow, see our Development +For an example of a fully automated development workflow, see the Development Workflow Guide. @@ -50,7 +50,7 @@ The workflow consists of three main phases: 1. **Patch**: If a critical bug is found, a patch is created and distributed to customers immediately via Shorebird. -Let's walk through each phase in more detail. +The following sections walk through each phase in more detail. ## Development phase @@ -280,9 +280,9 @@ The patch workflow can be broken down into the following steps: :::note - Here and in the GitHub Actions workflow below, we use a track named `staging` - to preview the hotfix in the staging environment. The name of the track is - arbitrary and can be changed to any name you prefer. + Here and in the GitHub Actions workflow below, a track named `staging` is + used to preview the hotfix in the staging environment. The name of the track + is arbitrary and can be changed to any name you prefer. ::: @@ -416,9 +416,9 @@ promoted to production. ## Recap -In this guide, we took a look at an opinionated development workflow with -Shorebird which allows teams to automate releasing and patching in order to -iterate quickly while still delivering a high-quality experience to customers. +This guide covered an opinionated development workflow with Shorebird that +allows teams to automate releasing and patching in order to iterate quickly +while still delivering a high-quality experience to customers. To see this workflow in action, check out the [Flutter & Friends Conference App](https://github.com/felangel/flutter_and_friends). diff --git a/src/content/docs/code-push/guides/flavors/android.mdx b/src/content/docs/code-push/guides/flavors/android.mdx index 90836931..387bdb24 100644 --- a/src/content/docs/code-push/guides/flavors/android.mdx +++ b/src/content/docs/code-push/guides/flavors/android.mdx @@ -24,9 +24,8 @@ more information. :::note -In this guide, we'll go through the process of creating a new project from -scratch. To apply these changes to an existing project, skip this step and read -ahead. +This guide walks through the process of creating a new project from scratch. To +apply these changes to an existing project, skip this step and read ahead. ::: @@ -104,7 +103,7 @@ may be necessary to avoid configuration issues. ::: Lastly, edit `android/app/src/main/AndroidManifest.xml` to use the -`applicationLabel` so that we can differentiate the two apps easily: +`applicationLabel` to easily differentiate the two apps: ```diff @@ -150,9 +149,8 @@ flavor, and you can validate the release flavor by visiting the ## Create a release -Now that we've created our apps on Shorebird, we need to create releases (one -for each flavor). To create a release, we'll use the `shorebird release android` -command. +Now that the apps have been created on Shorebird, releases need to be created +(one for each flavor), using the `shorebird release android` command. ```sh # Create a release for the internal flavor @@ -162,7 +160,7 @@ shorebird release android --flavor internal shorebird release android --flavor stable ``` -We can verify the releases were created successfully by visiting +Verify the releases were created successfully by visiting the [Shorebird console](https://console.shorebird.dev/). ## Preview the release @@ -201,10 +199,9 @@ stable variant should be promoted to production. ## Creating a patch -Now that we have our internal and stable releases on the Play Store, we can -create a patch using `shorebird patch android`. For the sake of this example, -let's adjust the app theme to use `deepOrange` as the seed color in -`lib/main.dart`: +Now that the internal and stable releases are on the Play Store, a patch can be +created using `shorebird patch android`. For the sake of this example, adjust +the app theme to use `deepOrange` as the seed color in `lib/main.dart`: ```diff class MyApp extends StatelessWidget { @@ -247,13 +244,13 @@ Typically `shorebird patch` should be used to fix critical bugs. ::: -Now that we've applied the changes, let's patch the `internal` variant: +Now that the changes have been applied, patch the `internal` variant: ```sh shorebird patch android --flavor internal ``` -We can validate the patch by visiting the +Validate the patch by visiting the [Shorebird console](https://console.shorebird.dev/), then selecting the internal release, or by relaunching the internal release. @@ -264,8 +261,8 @@ re-launch the app from the device or emulator directly. ::: -The first time the app is re-launched, we should still see the purple theme and -Shorebird will detect and install the patch in the background. Kill and +The first time the app is re-launched, the purple theme should still be visible, +and Shorebird will detect and install the patch in the background. Kill and re-launch the app a second time to see the applied patch. If all went well, you should see the patch was applied after re-launching the diff --git a/src/content/docs/code-push/guides/flavors/ios.mdx b/src/content/docs/code-push/guides/flavors/ios.mdx index 2cad8b73..545725eb 100644 --- a/src/content/docs/code-push/guides/flavors/ios.mdx +++ b/src/content/docs/code-push/guides/flavors/ios.mdx @@ -24,9 +24,8 @@ more information. :::note -In this guide, we'll go through the process of creating a new project from -scratch. To apply these changes to an existing project, skip this step and read -ahead. +This guide walks through the process of creating a new project from scratch. To +apply these changes to an existing project, skip this step and read ahead. ::: @@ -74,9 +73,8 @@ You can view your apps at ## Create a release -Now that we've created our apps on Shorebird, we need to create releases (one -for each flavor). To create a release, we'll use the `shorebird release ios` -command. +Now that the apps have been created on Shorebird, releases need to be created +(one for each flavor), using the `shorebird release ios` command. ```sh # Create a release for the internal flavor @@ -86,7 +84,7 @@ shorebird release ios --flavor internal shorebird release ios --flavor stable ``` -We can verify the releases were created successfully by visiting +Verify the releases were created successfully by visiting the [Shorebird console](https://console.shorebird.dev/). ## Preview the release @@ -125,9 +123,9 @@ stable variant should be promoted to production. ## Creating a patch -Now that we have our internal and stable releases on the App Store, we can -create a patch using `shorebird patch ios`. For the sake of this example, let's -adjust the app theme to use `deepOrange` as the seed color in `lib/main.dart`: +Now that the internal and stable releases are on the App Store, a patch can be +created using `shorebird patch ios`. For the sake of this example, adjust the +app theme to use `deepOrange` as the seed color in `lib/main.dart`: ```diff class MyApp extends StatelessWidget { @@ -164,13 +162,13 @@ class MyApp extends StatelessWidget { } ``` -Now that we've applied the changes, let's patch the `internal` variant: +Now that the changes have been applied, patch the `internal` variant: ```sh shorebird patch ios --flavor internal ``` -We can validate the patch by visiting +Validate the patch by visiting the [Shorebird console](https://console.shorebird.dev/) then select the internal release or re-launching the internal release. @@ -181,8 +179,8 @@ re-launch the app from the device or emulator directly. ::: -The first time the app is re-launched, we should still see the purple theme and -Shorebird will detect and install the patch in the background. Kill and +The first time the app is re-launched, the purple theme should still be visible, +and Shorebird will detect and install the patch in the background. Kill and re-launch the app a second time to see the applied patch. If all went well, you should see the patch was applied after re-launching the diff --git a/src/content/docs/code-push/guides/hybrid-apps/android.mdx b/src/content/docs/code-push/guides/hybrid-apps/android.mdx index eee8bc79..4d91c6ad 100644 --- a/src/content/docs/code-push/guides/hybrid-apps/android.mdx +++ b/src/content/docs/code-push/guides/hybrid-apps/android.mdx @@ -22,11 +22,11 @@ If your app is a pure Flutter app, follow the ## Prerequisites This guide assumes you have already have an Android app and a Flutter module. -Our Android app will be named `android_app` and our Flutter module will be named +The Android app will be named `android_app` and the Flutter module will be named `flutter_module`. This guide also assumes that you have created a Shorebird account. If you have -not, please see our [Code Push guide](/code-push/initialize) for instructions. +not, see the [Code Push guide](/code-push/initialize) for instructions. The reference code for this guide is available at https://github.com/shorebirdtech/samples/tree/main/add_to_app. @@ -98,9 +98,9 @@ dependencyResolutionManagement { :::note -Even though we are replacing https://storage.googleapis.com/download.flutter.io. -with https://download.shorebird.dev/download.flutter.io, any Flutter -dependencies that are not unique to Shorebird will still be downloaded from +Even though https://storage.googleapis.com/download.flutter.io is replaced with +https://download.shorebird.dev/download.flutter.io, any Flutter dependencies +that are not unique to Shorebird will still be downloaded from https://storage.googleapis.com/download.flutter.io. This will only work for versions of Flutter that Shorebird supports. @@ -155,7 +155,7 @@ Flutter symbols in your app. ## Submit your app to the Play Store -We won't cover this step in detail here, but this is where you would submit your +This step isn't covered in detail here, but this is where you would submit your app to the Play Store. For Code Push to work, it is important that you submit _with the same `aar` generated by the release command above_. diff --git a/src/content/docs/code-push/guides/hybrid-apps/ios.mdx b/src/content/docs/code-push/guides/hybrid-apps/ios.mdx index b3c37b3b..e7982bb4 100644 --- a/src/content/docs/code-push/guides/hybrid-apps/ios.mdx +++ b/src/content/docs/code-push/guides/hybrid-apps/ios.mdx @@ -25,12 +25,12 @@ If your app is a pure Flutter app, follow the ## Prerequisites -This guide assumes you have already have an iOS app and a Flutter module. Our -iOS app will be named `IosCodePushDemo` and our Flutter module will be named -`flutter_module`. +This guide assumes you have already have an iOS app and a Flutter module. The +example iOS app will be named `IosCodePushDemo` and the example Flutter module +will be named `flutter_module`. This guide also assumes that you have created a Shorebird account. If you have -not created a Shorebird account, please see our +not created a Shorebird account, please see the [Code Push guide](/code-push/initialize) for instructions. The reference code for this guide is available at @@ -41,7 +41,7 @@ https://github.com/shorebirdtech/samples/tree/main/add_to_app. Shorebird only supports the iOS Framework embedding method of adding Flutter to a native iOS app (see "Use iOS frameworks" in the [official integration docs](https://docs.flutter.dev/add-to-app/ios/project-setup)). -We have an open issue to support embedding via CocoaPods +There is an open issue to support embedding via CocoaPods ([link](https://github.com/shorebirdtech/shorebird/issues/1198)), but given that [Flutter plans to deprecate CocoaPods support](https://github.com/flutter/flutter/issues/168015), it is unlikely that this will be implemented. @@ -58,9 +58,9 @@ shorebird init ## Create a Shorebird release -First, we need to package our Flutter module for release. This will produce an -`.xcframework` that we can embed in our iOS app and provide Shorebird with the -information it needs to apply patches. +First, package the Flutter module for release. This will produce an +`.xcframework` that can be embedded in your iOS app and provides Shorebird with +the information it needs to apply patches. To create a release, run the following the root directory of your Flutter module: @@ -107,9 +107,9 @@ to the official docs. :::note `ShorebirdFlutter.xcframework` is nearly identically to `Flutter.xcframework` -from Google, but as part of compliance with Apple's signing requirements, we've -renamed the framework when applying Shorebird (legally Code Town, Inc's) digital -signature. +from Google, but as part of compliance with Apple's signing requirements, the +framework has been renamed when applying Shorebird's (legally Code Town, Inc's) +digital signature. ::: @@ -139,7 +139,7 @@ Content" section. Make sure to select "Embed & Sign" for both frameworks. :::note You may also see that `ShorebirdFlutter.xcframework` is signed by Code Town Inc. -That's us 🙂 +That's the Shorebird team 🙂 ::: @@ -155,7 +155,7 @@ and you should see debug logs from Shorebird. ## Submit your app to the App Store -We won't cover this step in detail here, but this is where you would submit your +This step isn't covered in detail here, but this is where you would submit your app to the App Store. For Code Push to work, it is important that you submit _with the same `xcframework` generated by the release command above_. @@ -171,7 +171,7 @@ shorebird patch ios-framework --release-version 1.2.3+4 `release-version` should be the version of the iOS app you released with the output of the `release` command. As before, this should match your app's version -and build numbers in Xcode. The command above will patch the release we created +and build numbers in Xcode. The command above will patch the release created earlier in this guide. You can now test the patch in your app by running the app from Xcode. After the diff --git a/src/content/docs/code-push/guides/patch-signing.mdx b/src/content/docs/code-push/guides/patch-signing.mdx index 0494a83d..685c8123 100644 --- a/src/content/docs/code-push/guides/patch-signing.mdx +++ b/src/content/docs/code-push/guides/patch-signing.mdx @@ -5,9 +5,9 @@ sidebar: order: 19 --- -In addition to our default security measures, Shorebird also provides patch -signing for additional security. This is optional at this time and needs to be -set up during your build and patch process. +In addition to Shorebird's default security measures, Shorebird also provides +patch signing for additional security. This is optional at this time and needs +to be set up during your build and patch process. Patch signing allows developers to cryptographically sign patch updates with their own keys. This ensures that no one (including Shorebird) can change the @@ -61,8 +61,8 @@ Shorebird credentials), it should not be checked into public source control. ### Key storage Shorebird does not provide a Key Storage solution at this time. If you are using -this feature, we highly recommend using a cloud key management service instead -of just storing keys on disk. **If for any reason you were to lose your private +this feature, using a cloud key management service instead of just storing keys +on disk is highly recommended. **If for any reason you were to lose your private key, there is no way to create a patch for an application containing the corresponding public key.** Even Shorebird is not able to create a patch for your application without your private key. In such a case, you would need to @@ -158,10 +158,10 @@ crash. ## Trade-offs -Signature verification does add a small overhead at app launch. During our -testing this has been observed to be under 50ms with a medium-sized app on a -5-year-old Android phone. This overhead increases with application size. For -very large apps, if this overhead shows up on your benchmarks, you can set +Signature verification does add a small overhead at app launch. During testing +this has been observed to be under 50ms with a medium-sized app on a 5-year-old +Android phone. This overhead increases with application size. For very large +apps, if this overhead shows up on your benchmarks, you can set `patch_verification: install_only` in `shorebird.yaml` to verify signatures only when patches are installed rather than on every launch. diff --git a/src/content/docs/code-push/guides/percentage-based-rollouts.mdx b/src/content/docs/code-push/guides/percentage-based-rollouts.mdx index 88fc282f..c13d9b11 100644 --- a/src/content/docs/code-push/guides/percentage-based-rollouts.mdx +++ b/src/content/docs/code-push/guides/percentage-based-rollouts.mdx @@ -17,7 +17,7 @@ system using predefined tracks. The sample code for this guide can by found at https://github.com/shorebirdtech/samples/tree/main/progressive_rollout_demo -Our percentage-based rollout system will have the following three parts: +This percentage-based rollout system has three parts: 1. Using Shorebird's “tracks” feature to publish patches to different sets of users. @@ -54,8 +54,8 @@ auto_update: false ## Add logic to bucket your users -We do this by assigning each user a number between 1 and 100 and saving that -value to a local cache using +Do this by assigning each user a number between 1 and 100 and saving that value +to a local cache using [`package:shared_preferences`](https://pub.dev/packages/shared_preferences): ```dart @@ -77,8 +77,8 @@ Future main() async { ## Add logic to determine rollout percentage -We've used Firebase's Cloud Firestore to create a simple key-value pairing of -release versions to rollout percentages, although any method of retrieving a +This guide uses Firebase's Cloud Firestore to create a simple key-value pairing +of release versions to rollout percentages, although any method of retrieving a rollout percentage from the cloud will work. ```dart @@ -94,9 +94,9 @@ Future _fetchRolloutPercentage() async { ## Use these values to choose a track -We can now tie this all together by using the group number and the rollout -percentage to decide whether a user should get patches in the beta track or in -the stable track. +Now, tie this all together by using the group number and the rollout percentage +to decide whether a user should get patches in the beta track or in the stable +track. ```dart Future _updateTrack() async { @@ -118,7 +118,7 @@ Future _updateTrack() async { ## Seeing it in action -We'll start by creating a release for Android: +Start by creating a release for Android: ``` shorebird release android @@ -128,23 +128,23 @@ This will create a release build of your app (an aab file) that is patchable with Shorebird. You will distribute this build to your users the same way you distribute your apps today. -Now, we'll launch our example using `shorebird preview`, which downloads the -release and runs it on a local device: +Now, launch the example using `shorebird preview`, which downloads the release +and runs it on a local device: Release build showing group number 76 with a red background -We can see from this screenshot that our device is in group 76. This means that -we will request patches on the stable track until our rollout percentage is >= -76, at which point we will start requesting patches in the beta track. +This screenshot shows that the device is in group 76. This means that it will +request patches on the stable track until the rollout percentage is >= 76, at +which point it will start requesting patches in the beta track. -Because we haven't created a patch on the beta track or set a rollout percentage -yet, there isn't much to see yet. +Because a patch hasn't been created on the beta track or a rollout percentage +set yet, there isn't much to see yet. -Let's change the background color from `Colors.deepPurple` to `Colors.red` and -create a patch on the beta track using the following command: +Change the background color from `Colors.deepPurple` to `Colors.red` and create +a patch on the beta track using the following command: ``` shorebird patch android --track=beta @@ -157,7 +157,7 @@ And update the rollout percentage in Firebase: alt="Cloud Firestore showing 1.0.0+1 at 50% rollout" /> -Press the update button, and our Shorebird preview output shows the following +Press the update button, and the Shorebird preview output shows the following (formatted for readability): ``` @@ -171,14 +171,14 @@ Press the update button, and our Shorebird preview output shows the following } ``` -Now if we change the rollout percentage in Firebase to 76%: +Now, change the rollout percentage in Firebase to 76%: Cloud Firestore showing 1.0.0+1 at 76% rollout -And press the update button again, we will now see: +Press the update button again, and you'll now see: ``` 11-13 16:41:42.525 7036 7102 I flutter : updater::network: @@ -207,7 +207,7 @@ And press the update button again, we will now see: ``` Note that the channel field in the patch check request has changed from stable -to beta, and that we've downloaded our patch. +to beta, and that the patch has been downloaded. ```bash title="Android" @@ -69,7 +67,7 @@ shorebird release macos -We can verify the releases were created successfully by visiting +Verify the releases were created successfully by visiting the [Shorebird console](https://console.shorebird.dev). You should also @@ -79,8 +77,8 @@ and ## Creating a patch -Now that we have our releases on the Play Store and App Store, we can create a -patch using `shorebird patch`. For the sake of this example, let's set the +Now that the releases are on the Play Store and App Store, a patch can be +created using `shorebird patch`. For the sake of this example, set the `backgroundColor` of the `Scaffold` to `Colors.cyan` in `lib/main.dart`: ```diff @@ -108,7 +106,7 @@ class MainApp extends StatelessWidget { ``` -Now that we've applied the changes, let's create a patch: +Now that the changes have been applied, create a patch: ```bash title="Android" @@ -138,9 +136,9 @@ shorebird preview --track staging --app-id ee322dc4-3dc2-4324-90a9-04c40a62ae76 Shorebird will download the release and run it on your device in the staging environment. -The first time the app is re-launched, we should still see the white `Scaffold` -and Shorebird will detect and install the patch in the background. Kill and -re-launch the app a second time to see the applied patch with the cyan +The first time the app is re-launched, the white `Scaffold` should still be +visible, and Shorebird will detect and install the patch in the background. Kill +and re-launch the app a second time to see the applied patch with the cyan `Scaffold` background. If all went well, you should see the patch was applied after re-launching the diff --git a/src/content/docs/code-push/guides/stores/app-store.mdx b/src/content/docs/code-push/guides/stores/app-store.mdx index 55b6401d..7c4b064a 100644 --- a/src/content/docs/code-push/guides/stores/app-store.mdx +++ b/src/content/docs/code-push/guides/stores/app-store.mdx @@ -24,8 +24,8 @@ import appStoreConnectReviewIssues from '~/assets/app_store_connect_review_issue This guide walks through releasing a Code Push app to the Apple App Store and applying a patch to that release. -The app we will be releasing in this guide is Shorebird Clock, our demo code -push app. ([source](https://github.com/shorebirdtech/time_shift/)) +The app used in this guide is Shorebird Clock, a demo Code Push app. +([source](https://github.com/shorebirdtech/time_shift/)) ## Prerequisites @@ -47,8 +47,8 @@ To follow along with this guide, you will need the following: ### Specify a development team in Xcode -To build an iOS app for distribution, we need to specify a development team in -Xcode. Open `ios/Runner.xcworkspace` in Xcode and select the `Runner` target: +To build an iOS app for distribution, a development team needs to be specified +in Xcode. Open `ios/Runner.xcworkspace` in Xcode and select the `Runner` target: Xcode development team @@ -57,8 +57,8 @@ Xcode. Open `ios/Runner.xcworkspace` in Xcode and select the `Runner` target: ### Determine the release version Navigate to your app on the [Shorebird console](https://console.shorebird.dev/) -to see the current set of releases. For our app, we see that the latest release -version is `1.0.3+1`, so the version of our next release will be `1.0.4+1`. +to see the current set of releases. For this example app, the latest release +version is `1.0.3+1`, so the version of the next release will be `1.0.4+1`. ### Create a release in App Store Connect @@ -187,14 +187,14 @@ After a short delay (usually a minute or two), you will see the build listed as App Store Connect Processing -Once the app has finished processing, we can add it to our release: +Once the app has finished processing, it can be added to the release: App Store Connect add build ## Submit the app for review -When we attempt to submit the app for review, App Store Connect will list the -issues we need to resolve before we can submit the app: +When you attempt to submit the app for review, App Store Connect will list the +issues that need to be resolved before the app can be submitted: -We recommend using one of the following three approaches to distribute patches +Using one of the following three approaches is recommended to distribute patches to a subset of users (e.g. your QA team) for testing without affecting your public users in production. @@ -41,8 +41,8 @@ more advanced control over the update process. ### Option 1: Control Shorebird track based on the current user’s account. -If your app has a login mechanism, this is your best option. If it does not, we -recommend option 2. +If your app has a login mechanism, this is your best option. If it does not, +option 2 is recommended. Once your user has logged in, you determine whether the user is a tester and then change your Shorebird update code to use that information when updating, @@ -56,12 +56,12 @@ shorebirdUpdater.update(track: track); ### Option 2: Control Shorebird track with a hidden UI. If your app does not have a login/user-account mechanism, this is your best -option. If it does, we recommend option 1. +option. If it does, option 1 is recommended. -Some stores discourage hidden UIs; however our customers tell us it is common -practice. For example, some apps may enable a “QA” mode in their app after a -certain series of clicks or special gestures, etc., similar to how Android -enables developer mode when +Some stores discourage hidden UIs; however, this is a common practice among +Shorebird customers. For example, some apps may enable a “QA” mode in their app +after a certain series of clicks or special gestures, etc., similar to how +Android enables developer mode when [tapping 7 times on the Android version text in the settings app](https://developer.android.com/studio/debug/dev-options) From a QA mode, you could allow testers to switch to the “beta” patch track, even from your production app. They could similarly switch back to “stable” to @@ -79,7 +79,7 @@ It is then possible to pick the Shorebird track based on the detected install mechanism, allowing you to thus distribute patches _only_ to your TestFlight users, etc. -Because detection of install mechanisms can be unreliable, we recommend option 1 -or 2 for most teams, but include this option for completeness. Most teams who -distribute via TestFlight, for example, also have QA-specific accounts and thus -option 2 is strictly better. +Because detection of install mechanisms can be unreliable, option 1 or 2 is +recommended for most teams, but this option is included for completeness. Most +teams who distribute via TestFlight, for example, also have QA-specific accounts +and thus option 2 is strictly better. diff --git a/src/content/docs/code-push/guides/white-labeling.mdx b/src/content/docs/code-push/guides/white-labeling.mdx index f249d2d7..5e2fbb75 100644 --- a/src/content/docs/code-push/guides/white-labeling.mdx +++ b/src/content/docs/code-push/guides/white-labeling.mdx @@ -7,10 +7,10 @@ sidebar: :::note -This is a placeholder article. We seem to have many customers using Shorebird -within a white labeling environment, but we have little personal experience with -white labeling and love to work with someone to update this document to include -your best practices. +This is a placeholder article. Shorebird seems to have many customers using it +within a white labeling environment, but the Shorebird team has little personal +experience with white labeling and would love to work with someone to update +this document to include your best practices. ::: @@ -32,7 +32,7 @@ course. There are different methods for white-labeling applications, Shorebird currently does not offer any automation tooling for any specific method, however it should -be straightforward to build on top of what we do offer. +be straightforward to build on top of what Shorebird does offer. For example, imagine you use per-customer flavors. You could imagine doing something like this: diff --git a/src/content/docs/code-push/index.mdx b/src/content/docs/code-push/index.mdx index 734e3f58..e26c507f 100644 --- a/src/content/docs/code-push/index.mdx +++ b/src/content/docs/code-push/index.mdx @@ -172,7 +172,7 @@ Patches are created by running `shorebird patch [platform]`, where `platform` is :::note -For more information regarding when to create a patch, refer to our +For more information regarding when to create a patch, refer to the [FAQs](/code-push/faq#when-should-i-create-a-patch-vs-a-release). ::: diff --git a/src/content/docs/code-push/patch.mdx b/src/content/docs/code-push/patch.mdx index 4bb46aaf..7b380d77 100644 --- a/src/content/docs/code-push/patch.mdx +++ b/src/content/docs/code-push/patch.mdx @@ -176,7 +176,7 @@ iOS and macOS patching works, see [System Architecture](/code-push/system-architecture). If you ever see unexpected performance changes when patching, please -[contact us](mailto:contact@shorebird.dev), and we would love to help. +[reach out](mailto:contact@shorebird.dev) for help. --- diff --git a/src/content/docs/code-push/performance.mdx b/src/content/docs/code-push/performance.mdx index 68ccf979..85cb9468 100644 --- a/src/content/docs/code-push/performance.mdx +++ b/src/content/docs/code-push/performance.mdx @@ -8,11 +8,12 @@ sidebar: Shorebird uses its own fork of Flutter. -Our fork works exactly as Google's does, including passing all the same +Shorebird's fork works exactly as Google's does, including passing all the same functionality and performance tests. Using Shorebird's fork should not result in any change in your app. If you ever -see any change, please let us know so we can work with you to diagnose. +see any change, reach out on [Discord](https://discord.gg/shorebird) so the +Shorebird team can help diagnose. ### Patching @@ -80,11 +81,11 @@ in the compiled `isEven` code. (That's a good thing.) Unfortunately that means that when the new code now used `isEven` in a nullable context the compiled contents of "isEven" change, to include null checks. Since the contents of isEven changed, Shorebird will conservatively assume that the behavior of all -callers of `isEven` might have changed as well and we will not use the CPU -versions of those either. Thus if your change (however small) might happen to -have caused the Dart compiler to reconsider optimizations for some other -critical section of code, tiny changes can sometimes cause large sections of -your application to "un-link" and run in the interpreter. +callers of `isEven` might have changed as well and won't use the CPU versions of +those either. Thus if your change (however small) might happen to have caused +the Dart compiler to reconsider optimizations for some other critical section of +code, tiny changes can sometimes cause large sections of your application to +"un-link" and run in the interpreter. ### Avoiding performance changes in iOS patches @@ -98,13 +99,13 @@ Shorebird's tooling and console will warn you. The bad news is that predicting when a change will trigger the Dart compiler to cause non-local changes to your program is very difficult. -When these non-local changes occur, the best recommendation we have at this time -is to try to make a new, smaller diff, and patch again. +When these non-local changes occur, the best recommendation at this time is to +try to make a new, smaller diff, and patch again. For the vast majority of patches there is no performance difference at all. For those which do see a difference, sometimes that difference may still be worth the trade-off as a stop-gap between now and when a user can get an update via the App Store. -We have several approaches to explore to remove this limitation on iOS and -intend to continue to improve this behavior in the future. +Several approaches exist to remove this limitation on iOS, and Shorebird intends +to continue improving this behavior in the future. diff --git a/src/content/docs/code-push/release.mdx b/src/content/docs/code-push/release.mdx index 3caa1293..f8ca1d75 100644 --- a/src/content/docs/code-push/release.mdx +++ b/src/content/docs/code-push/release.mdx @@ -519,12 +519,12 @@ for that release. ## Side-loading and MDM -A common question we get asked is: Does Shorebird require publishing to the App -Store or Play Store? +A common question is: Does Shorebird require publishing to the App Store or Play +Store? No. Shorebird works fine with side-loading and mobile device management (MDM) on -Android. We haven't had anyone try Shorebird with the iOS Developer Enterprise -program, but we expect it to work just as well. +Android. No one has yet reported trying Shorebird with the iOS Developer +Enterprise program, but it's expected to work just as well. To build Shorebird for distribution via APK (e.g., side-loading), use the `--artifact` flag with the `shorebird release` command. For example: diff --git a/src/content/docs/code-push/rollback.mdx b/src/content/docs/code-push/rollback.mdx index 90512799..48029603 100644 --- a/src/content/docs/code-push/rollback.mdx +++ b/src/content/docs/code-push/rollback.mdx @@ -57,7 +57,7 @@ patch row, click the "more" icon (three vertical dots) and select "Rollback": ## What happens when a patch is rolled back? -Imagine we have a release with three patches: +Imagine a release with three patches: Initial app UI on Android -Before shipping anything, let’s make a small but visible change so you can see -how Flutter’s UI responds to code edits. We’ll tweak the app’s theme color and -update some on-screen text. +Before shipping anything, make a small but visible change so you can see how +Flutter’s UI responds to code edits. This next step tweaks the app’s theme color +and updates some on-screen text. Open **lib/main.dart** in your editor. Near the top of the file, you’ll find the `MaterialApp` widget. This is where global application settings live, including @@ -321,9 +321,9 @@ This fast feedback loop is one of Flutter’s biggest strengths. You edit Dart code, the framework rebuilds the widget tree, and the changes appear immediately. -In the next step, we’ll take this simple customization further by preparing the -app for its first Shorebird-powered release, setting the stage for OTA updates -that go beyond local development. +The next step takes this simple customization further by preparing the app for +its first Shorebird-powered release, setting the stage for OTA updates that go +beyond local development. ## Step 5: From development to release with Shorebird diff --git a/src/content/docs/flutter-concepts/flutter-sdk-deep-dive.mdx b/src/content/docs/flutter-concepts/flutter-sdk-deep-dive.mdx index 15042ae2..3acfbda9 100644 --- a/src/content/docs/flutter-concepts/flutter-sdk-deep-dive.mdx +++ b/src/content/docs/flutter-concepts/flutter-sdk-deep-dive.mdx @@ -62,8 +62,7 @@ long app store waits._ ## Flutter engine and the shift from Skia to Impeller -Another part of Flutter I’m commonly asked about is why Flutter has its own -rendering pipeline, Impeller. +Another common question is why Flutter has its own rendering pipeline, Impeller. The Flutter Engine is a portable C++ runtime providing the rendering pipeline, Dart VM integration, and platform abstraction layer. Historically, Flutter used @@ -94,8 +93,7 @@ animation-heavy applications. ## The three-tree architecture powers efficient UI updates -Another question I’m sometimes asked is how the Flutter interaction pipeline -works. +Another common question is how the Flutter interaction pipeline works. Flutter's framework layer maintains three parallel tree structures that work together for efficient rendering: @@ -223,8 +221,8 @@ in there too, and should be used with caution. **Unit tests** use the [test](https://pub.dev/packages/test) package to verify isolated functions and classes. External dependencies should be mocked using packages like [Mockito](https://pub.dev/packages/mockito). These execute in -milliseconds and catch logic errors early. I often find it particularly helpful -to separate my app into “ui” (Flutter) code and “logic” pure Dart code, and +milliseconds and catch logic errors early. It's often particularly helpful to +separate an app into “ui” (Flutter) code and “logic” pure Dart code, and extensively test the logic with unit tests. **Widget tests** use @@ -283,7 +281,7 @@ hotfix, or a targeted change. You can only ship a whole new app. ## Shorebird enables over-the-air Dart code updates -This release pain is one of the reasons we started Shorebird. +This release pain is one of the reasons Shorebird was started. [Shorebird](https://shorebird.dev/), solves the distribution problem through sophisticated engine modifications. The platform maintains forks of Flutter and Dart. When you install Shorebird, it provides custom Flutter and Dart copies @@ -339,8 +337,8 @@ analyzer: strict-inference: true ``` -We recommend running `flutter analyze` before commits and `dart fix --apply` to -automatically resolve deprecated API usage. For deeper analysis, +Run `flutter analyze` before commits and `dart fix --apply` to automatically +resolve deprecated API usage. For deeper analysis, [DCM (Dart Code Metrics)](https://dcm.dev/) provides complexity metrics and unused code detection. Also, use Shorebird for testing and deploying patches quickly to your released app. diff --git a/src/content/docs/flutter-concepts/state-management/advanced.mdx b/src/content/docs/flutter-concepts/state-management/advanced.mdx index 3f2b850e..7c40367a 100644 --- a/src/content/docs/flutter-concepts/state-management/advanced.mdx +++ b/src/content/docs/flutter-concepts/state-management/advanced.mdx @@ -6,13 +6,13 @@ sidebar: order: 2 --- -In the [Beginner Guide](/flutter-concepts/state-management/beginner), we -explored the core philosophy of BLoC and how to leverage the Single State + Enum -pattern to avoid screen flickering and preserve data. +The [Beginner Guide](/flutter-concepts/state-management/beginner) explored the +core philosophy of BLoC and how to leverage the Single State + Enum pattern to +avoid screen flickering and preserve data. -Now, let's put these professional state management practices into action by -building a fully-featured, production-ready weather app from scratch using BLoC, -the repository pattern, and HTTP integrations. +Now, put these professional state management practices into action by building a +fully-featured, production-ready weather app from scratch using BLoC, the +repository pattern, and HTTP integrations. This walkthrough will cover: @@ -339,7 +339,7 @@ layers later, your BLoC and UI layers remain unaffected. ### Step 3: define events -Next, we define our events. Events should name actions that happened. +Next, define the events. Events should name actions that happened. ```dart // lib/features/weather/bloc/weather_event.dart @@ -372,7 +372,7 @@ final class WeatherRefreshRequested extends WeatherEvent { ### Step 4: define states using the single state pattern Instead of creating separate classes for each state (which breaks data retention -during refreshes), we use a Single State Class with a status enum. +during refreshes), use a Single State Class with a status enum. ```dart // lib/features/weather/bloc/weather_state.dart @@ -410,9 +410,9 @@ class WeatherState extends Equatable { ### Step 5: Implement the BLoC -Now we write the business logic orchestrator. We use `copyWith` to emit state -modifications. Notice that during refreshes, we preserve the existing weather -data. +Now write the business logic orchestrator, using `copyWith` to emit state +modifications. Notice that during refreshes, the existing weather data is +preserved. ```dart // lib/features/weather/bloc/weather_bloc.dart @@ -481,7 +481,7 @@ class WeatherBloc extends Bloc { ### Step 6: Wiring It Into the UI -We split this feature layout into: +This feature layout is split into: - `WeatherPage` – Sets up the dependency injection context. - `WeatherView` – Owns the text controllers and renders states. diff --git a/src/content/docs/getting-started/flutter-version.mdx b/src/content/docs/getting-started/flutter-version.mdx index 26ed85ed..af300195 100644 --- a/src/content/docs/getting-started/flutter-version.mdx +++ b/src/content/docs/getting-started/flutter-version.mdx @@ -10,8 +10,8 @@ of Flutter installs which it will automatically manage for you to match your desired Flutter version. When Shorebird CLI is installed, it pulls down the latest stable version of -Shorebird's Flutter. In this section, we'll take a look at how to list and -change the Flutter version used by Shorebird CLI. +Shorebird's Flutter. This section covers how to list and change the Flutter +version used by Shorebird CLI. ## Supported Flutter versions @@ -24,8 +24,8 @@ change the Flutter version used by Shorebird CLI. | Linux | 3.29.0 | 1.6.17 | Shorebird recommends using the latest stable version of Flutter whenever -possible. When we make changes to Shorebird, we do not currently backport those -changes to previous releases of Flutter. +possible. Changes to Shorebird are not currently backported to previous releases +of Flutter. ## List Flutter versions @@ -63,9 +63,9 @@ always be built with the version of Flutter used by the release. ## Flutter version notes -To help you avoid hidden pitfalls, we maintain version notes on Flutter releases -that have known issues affecting releasing apps or patching. Check here before -upgrading or deploying. +To help you avoid hidden pitfalls, Shorebird maintains version notes on Flutter +releases that have known issues affecting releasing apps or patching. Check here +before upgrading or deploying. - November 18, 2025: Shorebird has skipped support for 3.38.0 given [an issue with the pinned Dart version](https://github.com/flutter/flutter/issues/178400). diff --git a/src/content/docs/getting-started/index.mdx b/src/content/docs/getting-started/index.mdx index 40053db5..399f9e8e 100644 --- a/src/content/docs/getting-started/index.mdx +++ b/src/content/docs/getting-started/index.mdx @@ -208,7 +208,7 @@ You can also see your current version at any time by running ## Sample apps If you want to see Shorebird in action in a production-like application, check -out our samples: +out these samples: