From 509a3ca180c56faa83ec42038f20bc4d33b0eced Mon Sep 17 00:00:00 2001 From: Tom Arra Date: Thu, 2 Jul 2026 14:51:46 -0500 Subject: [PATCH 01/13] docs: rewrite first-person voice in security, architecture, and FAQ pages Per the marketing content guidelines, docs should be written in second person. Rewrites the three largest offenders (230 of 487 total first-person pronoun instances): - system/security.mdx (139 instances): a security/policy page, almost entirely first-person statements about what Shorebird as a company does ("we use Google Cloud", "we do not sell your data"). These can't become "you" statements without changing the facts, so they're rephrased to third person ("Shorebird uses...") or passive voice instead. - code-push/system-architecture.mdx (48 instances): similar pattern - describes Shorebird's own internal architecture and fork history ("we forked Flutter", "our database"), rephrased the same way. - code-push/faq.mdx (43 instances): a mix of company statements (rephrased to third person/passive) and instructional recommendations ("we recommend X" -> "X is recommended" or dropped the pronoun entirely where the sentence reads fine without it). Left headings untouched even where they contain "we" (e.g. "What can't we use Shorebird Code Push for?") since Shorebird.SecondPerson is scoped to paragraphs only, not headings - these were never flagged and don't need to change. This is a partial pass; the remaining ~40 files with first-person instances will follow in subsequent commits. --- src/content/docs/code-push/faq.mdx | 132 ++++----- .../docs/code-push/system-architecture.mdx | 132 +++++---- src/content/docs/system/security.mdx | 278 +++++++++--------- 3 files changed, 269 insertions(+), 273 deletions(-) diff --git a/src/content/docs/code-push/faq.mdx b/src/content/docs/code-push/faq.mdx index 6555d818..30043035 100644 --- a/src/content/docs/code-push/faq.mdx +++ b/src/content/docs/code-push/faq.mdx @@ -5,28 +5,28 @@ sidebar: order: 13 --- -Still have a question about Shorebird Code Push that our docs didn't cover? +Still have a question about Shorebird Code Push that the docs didn't cover? You're in the right place. This page covers the most common questions. If you have a question not answered here or elsewhere in the docs, reach out on [Discord](https://discord.gg/shorebird) or -[file an issue](https://github.com/shorebirdtech/shorebird/issues). We're here -to help. +[file an issue](https://github.com/shorebirdtech/shorebird/issues). The +Shorebird team is happy to help. ## Getting started ### What is the difference between a patch and a release? -We use the term "release" to mean preparing a binary for the stores. In order to -later generate a patch Shorebird needs to know the exact binary that was shipped -to the stores. The `shorebird release` command is used to prepare a binary for -the stores which includes the Shorebird updater. +The term "release" means preparing a binary for the stores. In order to later +generate a patch Shorebird needs to know the exact binary that was shipped to +the stores. The `shorebird release` command is used to prepare a binary for the +stores which includes the Shorebird updater. -We use the term "patch" to mean a binary that can be applied to a release to -update it to new code. The `shorebird patch` command is used to generate a patch -from your new local code which is then diffed with the release binary to -generate a patch which is then shipped to your users. +The term "patch" means a binary that can be applied to a release to update it to +new code. The `shorebird patch` command is used to generate a patch from your +new local code which is then diffed with the release binary to generate a patch +which is then shipped to your users. -We explain more of these terms in [Overview](/code-push). +These terms are explained further in [Overview](/code-push). ### When should I create a patch vs a release? @@ -57,8 +57,8 @@ release, a patch, or both. Some of these polices include: 3. Continue to only use releases for shipping code changes, and only patch to fix critical bugs or make other emergency changes. -In the end, it comes down to what works for your business. We see most of our -current customers choosing option 2. +In the end, it comes down to what works for your business. Most current +customers choose option 2. :::note @@ -71,7 +71,7 @@ for distribution. Yes. Create an API key in the [Shorebird Console](https://console.shorebird.dev) under **Account → API Keys**, then add it to your CI environment as -`SHOREBIRD_TOKEN`. See our [CI setup guide](/code-push/ci/generic/) for detailed +`SHOREBIRD_TOKEN`. See the [CI setup guide](/code-push/ci/generic/) for detailed instructions. ### Can I use Dart defines with Shorebird? @@ -106,20 +106,20 @@ Shorebird is a fork of Flutter that adds Code Push. Shorebird is not a replacement for Flutter, but rather a replacement for the Flutter engine. You can continue to use the Flutter tooling you already know and love. -`shorebird` uses a fork of Flutter that includes the Shorebird updater. We track -the latest stable release of Flutter and replace a few of the Flutter engine -files with our modified copies. +`shorebird` uses a fork of Flutter that includes the Shorebird updater. +Shorebird tracks the latest stable release of Flutter and replaces a few of the +Flutter engine files with its modified copies. -To implement our fork, we use `FLUTTER_STORAGE_BASE_URL` to point to -`https://download.shorebird.dev` instead of download.flutter.dev. We pass -through unmodified output from the `flutter` tool so you will see a warning from +To implement its fork, Shorebird uses `FLUTTER_STORAGE_BASE_URL` to point to +`https://download.shorebird.dev` instead of download.flutter.dev. Unmodified +output from the `flutter` tool passes through, 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 +For more information about why Shorebird had to fork Flutter, see [System Architecture](/code-push/system-architecture). ### What platforms does Shorebird support? @@ -164,12 +164,12 @@ find the details of this on the ### What versions of Flutter does Shorebird support? -For specific versions by platform, please consult our +For specific versions by platform, please consult the [Flutter Version Management](/getting-started/flutter-version/) page. Shorebird tracks Flutter stable and generally updates within a few hours of any -stable release. Our system for doing these updates is automated. We then do an -extra manual verification step before publishing to our servers. +stable release. This process is automated, with an extra manual verification +step before publishing to Shorebird's servers. ### Can I use Shorebird with Flutter pre-release channels (Beta, Master)? @@ -236,9 +236,9 @@ Shorebird to violate Play Store guidelines is in violation of the Shorebird [Terms of Service](https://shorebird.dev/terms) and can result in termination of your account. -Code Push services are widely used in the industry (all of the large apps we're -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. +Code Push services are widely used in the industry (many large, well-known apps +use them) and there are multiple other Code Push services publicly available +(e.g. expo.dev & appcenter.ms). This is a well trodden path. Microsoft also publishes a guide on how their React Native "codepush" library complies with the app stores: @@ -279,9 +279,9 @@ https://github.com/microsoft/react-native-code-push#store-guideline-compliance ### Now that I'm using Shorebird, do I still need to send my app to the stores? -Yes. We recommend customers continue to release their app through the stores in -addition to using Shorebird. Even if this now means that there can be less -pressure on your app release process. +Yes. Continuing to release your app through the stores in addition to using +Shorebird is recommended, even though there can now be less pressure on your app +release process. This is for two reasons: @@ -289,28 +289,27 @@ This is for two reasons: review to avoid "deceiving users". Since apps are likely to change over time, periodic releases (to update store screenshots, etc.) is still good practice. 2. New users install from the stores, not Shorebird. Shorebird can only update - your application after launch, so for users to get the best first-launch - experience, we recommend that you continue to periodic releases to the - stores. + your application after launch, so periodic releases to the stores are still + recommended for the best first-launch experience. ### Does Shorebird submit to the stores for me? Shorebird does not currently support submitting to the app stores on your -behalf. We may end up adding this in the future, but for now you will need to -continue to use your existing processes to submit to the app stores. +behalf. This may be added in the future, but for now you will need to continue +to use your existing processes to submit to the app stores. ## Use cases & limitations ### What can I use Shorebird Code Push for? -We've seen a variety of uses, including: +Common uses include: - Emergency fixes to production apps. - Shipping bug fixes to users on older versions of your app. - Shipping constantly (e.g. daily, every commit to `main`, etc). Note that most app stores prohibit shipping code that changes the behavior of -the app in a significant way. Please see our +the app in a significant way. Please see the [Store Compliance section](#store-compliance) for more information. ### What can't we use Shorebird Code Push for? @@ -319,7 +318,7 @@ Shorebird does not support changing native code (e.g. Java/Kotlin on Android or Objective-C/Swift on iOS). The tool will warn you during an attempted patch if you have changed native code. -Shorebird should not be used to violate app store polices. Please see our +Shorebird should not be used to violate app store polices. Please see the [Store Compliance section](#store-compliance) for more information. ### Can I use Shorebird for all my Dart changes? @@ -387,7 +386,7 @@ during development. It requires building the Flutter engine with a debug-mode Dart VM which includes a just-in-time (JIT) Dart compiler. Code Push is a feature that allows you to change code on the device in -production. We will use a variety of different techniques to make this possible +production. A variety of different techniques are used 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. @@ -396,8 +395,8 @@ code and do not require a JIT Dart compiler. Code Push isn't needed for Flutter web. When a user opens a web app it downloads the latest version from the server if needed. -If you have a use case for Code Push with Flutter web, we'd -[love to know](mailto:contact@shorebird.dev). +If you have a use case for Code Push with Flutter web, +[reach out](mailto:contact@shorebird.dev) to let the Shorebird team know. ## Technical details @@ -453,7 +452,7 @@ user's device actually pulls down. These numbers are for Flutter 3.41.7 (April 2026). Earlier Shorebird engines were meaningfully larger — iOS overhead alone came down by roughly 2 MB on-disk -in the preceding month — and we continue to shrink the overhead; progress is +in the preceding month, and the overhead continues to shrink; progress is tracked in [shorebird#3715](https://github.com/shorebirdtech/shorebird/issues/3715). You can reproduce a rough measurement on your own app by comparing the output of @@ -491,7 +490,7 @@ Requests sent from the app to Shorebird servers include: - client_id (anonymous, aggregated, per-app identifier used to provide active user metrics) -The code for this is public in our +The code for this is public in the [updater package](https://github.com/shorebirdtech/updater/blob/main/library/src/network.rs) and can be reviewed at any time. @@ -517,9 +516,9 @@ issues. In the default update behavior, when the application launches it alerts the Shorebird updater, which spawns a separate thread to make a network request to -Shorebird's servers and ask for an update. We intentionally use a separate -thread to avoid affecting blocking anything else the application might be doing. -If the network request fails or times out, the updater will simply try to check +Shorebird's servers and ask for an update. A separate thread is used +intentionally to avoid blocking anything else the application might be doing. If +the network request fails or times out, the updater will simply try to check again next time the application launches. Shorebird command line tools (e.g. `shorebird patch`) require network @@ -547,8 +546,8 @@ See [Organizations](/account/orgs) for more information. ### Can I self-host Shorebird? No. Shorebird has no current plans to offer on-prem, self-host or cloud-prem -offerings. We would be happy to discuss with you any and all ways in which we -can improve our centrally hosted solution to best match your needs. +offerings. The Shorebird team is happy to discuss ways to improve the centrally +hosted solution to best match your needs. ### Does Code Push work with large applications? @@ -571,11 +570,11 @@ installed. ### Can I use Shorebird in my country? -We have not attempted to restrict access to Shorebird from any country. +Shorebird has not attempted to restrict access from any country. -We recognize that some countries have restrictions on what urls can be accessed -from within the country. Shorebird currently uses Google Cloud for hosting, -including Google Cloud Storage and Google Cloud Run. +Some countries have restrictions on what urls can be accessed from within the +country. Shorebird currently uses Google Cloud for hosting, including Google +Cloud Storage and Google Cloud Run. The following URLs are used by Shorebird: @@ -605,8 +604,8 @@ work. If your region requires use of [FLUTTER_STORAGE_BASE_URL](https://docs.flutter.dev/community/china) Shorebird -may not work for you at this time as we also use that environment variable as -part of our implementation. We have plans to +may not work for you at this time since it also uses that environment variable +as part of its implementation. There are plans to [remove this restriction](https://github.com/shorebirdtech/shorebird/issues/435) in the future. @@ -627,10 +626,10 @@ mechanisms for segmenting your users into groups and distributing specific versions of your apps to each. Unfortunately, not all of these mechanisms allow 3rd parties to detect when apps -are installed in any specific Test Track or via TestFlight. Thus, we do not have -reliable visibility into composition of these groups, and cannot reliably gate -access to Shorebird patches based on these groups. You can read a bit more about -this on Stack Overflow discussions specifically about +are installed in any specific Test Track or via TestFlight. Thus, there is not +reliable visibility into composition of these groups, and Shorebird cannot +reliably gate access to patches based on these groups. You can read a bit more +about this on Stack Overflow discussions specifically about [Android](https://stackoverflow.com/questions/53291007/can-an-android-application-identify-the-test-track-within-google-play) and [iOS](https://stackoverflow.com/questions/26081543/how-to-tell-at-runtime-whether-an-ios-app-is-running-through-a-testflight-beta-i). @@ -643,8 +642,8 @@ potential options: Android the easy way to accomplish this is through flavors. You may already have a dev flavor and prod flavor with different availability. You can thus patch your dev flavor, verify it and then separately patch your prod flavor. - We recommend using branches / tags in your version control to help keep track - of the sources associated with each release. + Using branches / tags in your version control is recommended to help keep + track of the sources associated with each release. - Track your own set of opt-in users, disable automatic updates, and trigger updates only for certain users via [package:shorebird_code_push](https://pub.dev/packages/shorebird_code_push). @@ -655,15 +654,15 @@ potential options: ### What counts as a "patch install" for Shorebird? For more details on this, please refer to the -[How We Bill](/account/billing/#how-we-bill) section of our +[How We Bill](/account/billing/#how-we-bill) section of the [Billing page](/account/billing/). ### How do I upgrade or downgrade my plan? To upgrade your plan, you can [subscribe via the Shorebird console](https://console.shorebird.dev/subscriptions/create). -If you would like to move from a monthly to a yearly plan, please reach out to -us via [email](mailto:billing@shorebird.dev) to complete the change. +If you would like to move from a monthly to a yearly plan, please reach out via +[email](mailto:billing@shorebird.dev) to complete the change. ### When does my billing period reset? @@ -682,6 +681,5 @@ your billing period. ### Can I pay for a year in advance? -Yes. We launched support for self-service yearly plans in April 2025. You can -read more about this in our -[announcement blog post](https://shorebird.dev/blog/yearly-plans/). +Yes. Self-service yearly plans launched in April 2025. You can read more about +this in the [announcement blog post](https://shorebird.dev/blog/yearly-plans/). diff --git a/src/content/docs/code-push/system-architecture.mdx b/src/content/docs/code-push/system-architecture.mdx index 5b92b8e0..9c20c6d0 100644 --- a/src/content/docs/code-push/system-architecture.mdx +++ b/src/content/docs/code-push/system-architecture.mdx @@ -72,17 +72,17 @@ restrictions about the mechanism through which iOS applications are allowed to update. Shorebird is designed to comply with those restrictions through use of a novel Dart interpreter. -On iOS, instead of compiling to the normal machine code, we instead compile to a +On iOS, instead of compiling to the normal machine code, Shorebird compiles to a modified format that can be then interpreted on device. Because interpreters are -slower than running compiled code directly on a CPU, we also have built -additional systems into Shorebird to minimize the use of our interpreter. +slower than running compiled code directly on a CPU, Shorebird has also built +additional systems to minimize the use of the interpreter. Even if you were to replace all of your app code via a patch (don't do that, it -would be deceptive to users and against Shorebird and store policies), we would -still expect to run the vast majority (e.g. 80%) of your patched Dart code using -the exiting compiled and signed Dart code in your store-distributed application. -This is because the vast majority of a typical Flutter application is actually -Flutter Framework code rather than application code. +would be deceptive to users and against Shorebird and store policies), the vast +majority (e.g. 80%) of your patched Dart code would still be expected to run +using the existing compiled and signed Dart code in your store-distributed +application. This is because the vast majority of a typical Flutter application +is actually Flutter Framework code rather than application code. Shorebird has made two major changes to Dart to facilitate patching well on iOS including: @@ -99,7 +99,7 @@ These two changes combined make it so that you should expect almost all out of the "previous" binary included in the IPA, and thus run full-speed on the CPU. -See also articles on our blog explaining +See also articles on the Shorebird blog explaining [How Code Push Works](https://shorebird.dev/blog/how-we-built-code-push/). ## Lifetime of a Shorebird Update @@ -113,8 +113,8 @@ your project. `shorebird release` builds your app using `flutter build` and then uploads the resulting binary to a private Google Cloud Storage bucket. The command also -creates a "release" record in our database that associates the app_id with the -release version. +creates a "release" record in Shorebird's database that associates the app_id +with the release version. `shorebird preview` can be used to download and run any of these privately stored release binaries on your local device. @@ -130,18 +130,18 @@ combined release and patch binaries. This "patch diff" is then uploaded to a public Google Cloud Storage bucket where it will be served to devices requesting an update with the corresponding app_id and release version. -`shorebird patch` also creates a record in our database that associates the -patch with the app_id and release version and alerts our "patch check" servers -that a new patch is available. Patches can optionally be "staged" when uploaded. -They will then not appear in patch checks until the patch "channel" is set to -"stable" by the developer in the Shorebird Console. +`shorebird patch` also creates a record in Shorebird's database that associates +the patch with the app_id and release version and alerts Shorebird's "patch +check" servers that a new patch is available. Patches can optionally be "staged" +when uploaded. They will then not appear in patch checks until the patch +"channel" is set to "stable" by the developer in the Shorebird Console. Release binaries which were built with Shorebird contain Shorebird's updater library. By default, the updater library will check for patches every time the app is started. This is done via a background thread to not slow down launch. -The updater code makes a single request to our "patch check" servers which are -again Google Cloud Run instances. The "patch check" servers respond with the URL -of the patch diff if one is available. +The updater code makes a single request to Shorebird's "patch check" servers, +which are also Google Cloud Run instances. The "patch check" servers respond +with the URL of the patch diff if one is available. A typical patch check is made via https, and contains: @@ -179,15 +179,15 @@ binary. The patch diff is a binary diff. The updater library also checks the hash of the patch diff to confirm download integrity. The hash is not meant to be a security feature, but rather a way to detect -errors in the patch diff. A common error we see is that developers -`shorebird release` with one source and then actually build and release a -different binary, resulting then in invalid patches. This hash helps detect such -errors. For added security, we also provide a way for you to +errors in the patch diff. A common error is developers running +`shorebird release` with one source and then actually building and releasing a +different binary, resulting in invalid patches. This hash helps detect such +errors. For added security, there's also a way for you to [sign your patches](/code-push/guides/patch-signing/) if needed as per your security requirements. The modified Flutter engine also reports successful or failed launch of a patch -back to our servers the next time it makes a patch check. +back to Shorebird's servers the next time it makes a patch check. A patch event contains: @@ -217,7 +217,7 @@ Shorebird consists of 3 major parts: 1. The `Shorebird CLI` tool that you use to build and deploy your app from the command line. 1. A modified Flutter engine that is include in your app. -1. Our public-cloud infrastructure which hosts your app's updates. +1. Shorebird's public-cloud infrastructure which hosts your app's updates. ### The `Shorebird CLI` @@ -232,7 +232,7 @@ servers. Code Push requires technical changes to the underlying Flutter engine. To make those changes required forking Flutter. -We had to fork 4 Flutter and Dart repositories to make Shorebird work: +Shorebird had to fork 4 Flutter and Dart repositories to make Code Push work: #### `flutter/buildroot` "the buildroot" @@ -241,9 +241,9 @@ the build scripts that are used to build the Flutter engine for various platforms. It's separate from `flutter/engine` in order to share code and configuration with the Fuchsia build system. -We forked this repository to make several small modifications: +This repository was forked to make several small modifications: -1. Expose our updater symbols from the Flutter engine up to +1. Expose Shorebird's updater symbols from the Flutter engine up to `package:shorebird_code_push` 1. Include `libunwind` since the @@ -255,14 +255,14 @@ library which is linked into the Flutter engine via a static library (`libupdater.a`) that exposes a C API. Because the default Flutter engine linking flags hide all symbols from linked -static libraries, and because we need to be able to expose the `shorebird\_\*` -symbols from `libupdater.a` to the Dart code, we made one change to `buildroot` -and then a second change to the `engine` to place the symbols on the allow-list. +static libraries, and because the `shorebird\_\*` symbols from `libupdater.a` +need to be exposed to the Dart code, one change was made to `buildroot` and a +second to the `engine` to place the symbols on the allow-list. :::note -You can see our buildroot changes on GitHub by comparing our trunk to the -upstream buildroot, e.g. master: +You can see Shorebird's buildroot changes on GitHub by comparing its trunk to +the upstream buildroot, e.g. master: https://github.com/flutter/buildroot/compare/master...shorebirdtech:buildroot:shorebird/dev ::: @@ -273,14 +273,15 @@ The [`flutter/engine`](https://github.com/flutter/engine/) repo contains C++ code that runs on the device. It is responsible for rendering the UI, handling input, and communicating with the host. -We forked this code to add the +This code was forked to add the [Shorebird Updater](https://github.com/shorebirdtech/updater), which lets the Flutter engine load new code from Shorebird's servers. :::note -Our Flutter Engine fork is public. You can see our engine changes on GitHub by -comparing our trunk to the upstream Flutter engine, e.g. for 3.22.0: +Shorebird's Flutter Engine fork is public. You can see the engine changes on +GitHub by comparing Shorebird's trunk to the upstream Flutter engine, e.g. for +3.22.0: https://github.com/flutter/engine/compare/3.22.0...shorebirdtech:engine:shorebird/dev ::: @@ -291,14 +292,15 @@ The [`flutter/flutter`](https://github.com/flutter/flutter/) repo contains the Dart code that runs on the device as well as the `flutter` tool that is used to build and run Flutter apps. -We forked this code to be able to deliver our modified Flutter engine to change -the version of the engine that the `flutter` tool uses and to include the -`shorebird.yaml` configuration as part of the asset bundle. +This code was forked to be able to deliver Shorebird's modified Flutter engine, +changing the version of the engine that the `flutter` tool uses, and to include +the `shorebird.yaml` configuration as part of the asset bundle. :::note -Our Flutter Framework fork is public. You can see our engine changes on GitHub -by comparing our trunk to the upstream Flutter Framework, e.g. for stable: +Shorebird's Flutter Framework fork is public. You can see the engine changes on +GitHub by comparing Shorebird's trunk to the upstream Flutter Framework, e.g. +for stable: https://github.com/flutter/flutter/compare/stable...shorebirdtech:flutter:shorebird/dev ::: @@ -308,33 +310,33 @@ https://github.com/flutter/flutter/compare/stable...shorebirdtech:flutter:shoreb The [`dart-lang/sdk`](https://github.com/dart-lang/sdk/) repo contains the Dart SDK, including the VM, dart2js, core libraries, and more. -We forked this code in order to teach Dart how to run modified (patched) code in -an interpreter while being able to run all unmodified code on the CPU. +This code was forked in order to teach Dart how to run modified (patched) code +in an interpreter while being able to run all unmodified code on the CPU. :::note -Our Dart SDK fork is private currently. It will likely be public in the future -and we will work to upstream many our changes as the team grows and the product -matures. +Shorebird's Dart SDK fork is private currently. It will likely be public in the +future, and there are plans to upstream many changes as the team grows and the +product matures. ::: #### Installing a forked Flutter -When you install Shorebird, it installs Flutter and Dart from our fork. These -are currently not exposed on the user's path, rather private copies that +When you install Shorebird, it installs Flutter and Dart from Shorebird's fork. +These are currently not exposed on the user's path, rather private copies that Shorebird will use when building your app. This was necessary to avoid conflicts with other Flutter installations on the user's machine. Specifically, the way that Flutter downloads artifacts is based -on the version of the engine. If we were to use the same version of the engine -as the user's Flutter installation, then we would overwrite the user's engine +on the version of the engine. If Shorebird were to use the same version of the +engine as the user's Flutter installation, it would overwrite the user's engine artifacts. -We deliver our artifacts to this fork of Flutter with two ways. First is we -change the version of the engine in the `flutter` tool. Second is we pass +Shorebird delivers its artifacts to this fork of Flutter in two ways: first, by +changing the version of the engine in the `flutter` tool, and second, by passing `FLUTTER_STORAGE_BASE_URL` set to `download.shorebird.dev` (instead of -`download.flutter.io`) when calling our vended copy of the `flutter` tool. +`download.flutter.io`) when calling its vended copy of the `flutter` tool. Currently this means `shorebird` will not work in an environment where the user needs to use `FLUTTER_STORAGE_BASE_URL` to download Flutter artifacts from a @@ -343,17 +345,17 @@ https://github.com/shorebirdtech/shorebird/issues/237 #### Serving forked binaries -We also use a custom server to handle requests from `flutter` for our modified +A custom server is also used to handle requests from `flutter` for the modified engine. The source for that server is here: https://github.com/shorebirdtech/shorebird/tree/main/packages/artifact_proxy The artifact proxy is hosted at https://download.shorebird.dev via Google Cloud Run. -This proxy knows how to serve the modified binaries from our Google Storage -bucket, as well as how to forward along requests to Google's Flutter storage -bucket for unmodified binaries for all parts of Flutter we didn't have to -modify. +This proxy knows how to serve the modified binaries from Shorebird's Google +Storage bucket, as well as how to forward along requests to Google's Flutter +storage bucket for unmodified binaries for all parts of Flutter that didn't need +to be modified. ### Shorebird's cloud infrastructure @@ -364,11 +366,11 @@ app's updates. It's a set of services that handle the following: - Patch binary (public) storage and serving (via global CDN) - Patch check requests (via Google Cloud Run) -We also provide a web-based console for developers to manage their apps and view -analytics as well as the underlying database that powers the patch checks and -console. +Shorebird also provides a web-based console for developers to manage their apps +and view analytics, as well as the underlying database that powers the patch +checks and console. -The majority of our infrastructure is hosted on Google Cloud Platform although -we will likely expand to other cloud providers over time. For a full list of -providers see our [privacy policy](https://shorebird.dev/privacy/). All of these -services are currently set to use US regions by default. +The majority of Shorebird's infrastructure is hosted on Google Cloud Platform, +although it will likely expand to other cloud providers over time. For a full +list of providers see the [privacy policy](https://shorebird.dev/privacy/). All +of these services are currently set to use US regions by default. diff --git a/src/content/docs/system/security.mdx b/src/content/docs/system/security.mdx index 2cee39f1..aa5f7417 100644 --- a/src/content/docs/system/security.mdx +++ b/src/content/docs/system/security.mdx @@ -3,9 +3,9 @@ title: Security description: Security practices of the Shorebird system --- -This is our public security policy for the Shorebird system and products. This -document exists both for educating our employees as well as for reference by our -customers. +This is Shorebird's public security policy for the Shorebird system and +products. This document exists to educate Shorebird employees and to serve as a +reference for customers. Authorship and change history for this policy are visible in the git history of this document. @@ -16,16 +16,16 @@ Changes or exceptions to these policies should be reviewed by the CEO. ## About Shorebird -Shorebird is a software application. Most of our code is open source and -publicly reviewable on GitHub. We use Google Cloud for the bulk of our +Shorebird is a software application. Most of its code is open source and +publicly reviewable on GitHub. Shorebird uses Google Cloud for the bulk of its infrastructure. -Shorebird takes security very seriously. We take several steps to make sure that -we protect the data you give us, require only data that is absolutely necessary -for product functionality, and ensure that only you can publish changes to your -account and applications. +Shorebird takes security very seriously, taking several steps to protect the +data you give it, requiring only data that is absolutely necessary for product +functionality, and ensuring that only you can publish changes to your account +and applications. -Shorebird only offers a hosted service at this time. We do not currently offer +Shorebird only offers a hosted service at this time and does not currently offer [on-prem or cloud-prem](https://github.com/shorebirdtech/shorebird/issues/485) solutions. @@ -34,49 +34,48 @@ solutions. This document is focused on the specifics of the Shorebird system and product. If there are questions that relate to the overall company security policy, please refer to the -[Compliance section in our Handbook](https://handbook.shorebird.dev/compliance/). +[Compliance section in the Shorebird Handbook](https://handbook.shorebird.dev/compliance/). ## Terms -Throughout this document, we will refer to the following terms: +Throughout this document, the following terms are used: - Customer / you: A user of Shorebird. - End User: A user of a Customer's application. ## Acceptable use -Use of Shorebird is governed by our -[Terms of Service](https://shorebird.dev/terms). We have logging and alerting in -place to ensure that our service is not used for malicious purposes or such that +Use of Shorebird is governed by the +[Terms of Service](https://shorebird.dev/terms). Logging and alerting are in +place to ensure the service is not used for malicious purposes or in a way that would disrupt the service for other users. ## Infrastructure -Shorebird is hosted on Google Cloud. We use Google Cloud's security features to -secure our infrastructure. We have a dedicated VPC for our infrastructure. +Shorebird is hosted on Google Cloud and uses Google Cloud's security features to +secure its infrastructure, including a dedicated VPC. -Currently, Shorebird only uses Google Cloud's Iowa region. We have plans to -expand to other regions in the future for our international customers. +Currently, Shorebird only uses Google Cloud's Iowa region, with plans to expand +to other regions in the future for international customers. -Shorebird uses Google Cloud's managed services where possible. We do not manage -custom versions of software or operating systems, but instead rely on Google -Cloud to manage and update these services on a daily basis. For example, our -application end points use Google Cloud Run which is a managed service that -lives no longer than an hour, allowing Google to manage the underlying -infrastructure including patching continuously. Other parts of our -infrastructure are similar. +Shorebird uses Google Cloud's managed services where possible, relying on Google +Cloud to manage and update these services daily rather than managing custom +versions of software or operating systems. For example, Shorebird's application +endpoints use Google Cloud Run, a managed service that lives no longer than an +hour, allowing Google to continuously manage the underlying infrastructure +including patching. Other parts of Shorebird's infrastructure are similar. ### Architecture -We have written more on the architecture of Shorebird in our +More detail on Shorebird's architecture is available in the [architecture documentation](/code-push/system-architecture/). ### Shorebird servers `shorebird` tools communicate with Shorebird's cloud on your behalf. Shorebird -exclusively uses public cloud infrastructure and does not maintain our own -custom servers. We use Google Cloud and Cloudflare for all of our publicly -accessible endpoints. +exclusively uses public cloud infrastructure and does not maintain custom +servers, using Google Cloud and Cloudflare for all publicly accessible +endpoints. The following URLs are used by Shorebird. @@ -99,30 +98,30 @@ company network. ### Product access control -Shorebird accounts are managed through Google or Microsoft SSO (OAuth). We -intentionally do not support other access methods and do not store passwords for -our users. +Shorebird accounts are managed through Google or Microsoft SSO (OAuth). +Shorebird intentionally does not support other access methods and does not store +passwords for users. Shorebird accounts provide role-based access control on a per-application basis, -which is described in our [Organizations product documentation](/account/orgs/). +which is described in the [Organizations product documentation](/account/orgs/). ### Production access -We use [Google Cloud IAM](https://cloud.google.com/iam) for access control and -[Google Cloud Logging](https://cloud.google.com/logging) for logging. +Shorebird uses [Google Cloud IAM](https://cloud.google.com/iam) for access +control and [Google Cloud Logging](https://cloud.google.com/logging) for +logging. -A small number of engineers have access to production systems, for which we have -a dedicated machine for access. Production changes are all done via CI/CD -pipelines, as detailed in the Change Management section. +A small number of engineers have access to production systems, using a dedicated +machine for that access. Production changes are all done via CI/CD pipelines, as +detailed in the Change Management section. -We have an additional (read-only) admin layer to a subset of our production -systems for monitoring and support purposes. +Shorebird has an additional (read-only) admin layer to a subset of its +production systems for monitoring and support purposes. ### Network access -Shorebird is a web application. We use HTTPS for all communication between our -application and our customers. We use Google Cloud's managed SSL certificates -for this. +Shorebird is a web application that uses HTTPS for all communication with +customers, using Google Cloud's managed SSL certificates for this. Use of Shorebird requires access to the following web addresses: @@ -137,110 +136,106 @@ See also https://docs.shorebird.dev/faq/#can-i-use-shorebird-in-my-country. ### User access review -We review all user access to our systems periodically, as well as when an +User access to Shorebird's systems is reviewed periodically, as well as when an employee joins or leaves the company. All access to Shorebird systems is gated through Google SSO, including required two-factor authentication. ### Network security -Both our application and our infrastructure are hosted on Google Cloud. We use -Google Cloud's network security features to secure our infrastructure, including -restricting all public access to our infrastructure outside of our application -endpoint. +Both Shorebird's application and infrastructure are hosted on Google Cloud, +using Google Cloud's network security features to secure the infrastructure, +including restricting all public access outside of the application endpoint. -We have dedicated machines for access directly to our production environment, -access to such is restricted to a small number of engineers and is logged. +Dedicated machines are used for direct access to the production environment; +access is restricted to a small number of engineers and is logged. #### Intrusion detection / prevention / monitoring -We rely on Google Cloud network security for network-level intrusion detection. -We do log all actions within our systems and do regularly review these logs as -well as maintain alerting which is delivered to our engineering teams, both for -our web products as well as our backend database and servers. +Shorebird relies on Google Cloud network security for network-level intrusion +detection. All actions within Shorebird's systems are logged and regularly +reviewed, and alerting is maintained and delivered to the engineering team for +both web products and backend database and servers. ## Change management ### Code reviews All code should be reviewed by at least one other engineer before being merged. -We have branch policies in place on all of our repositories to ensure such. This -is done in service of security, but also in service of code quality. We believe -that code reviews are the best way to ensure that code is secure, maintainable, -and understandable. +Branch policies are in place on all repositories to ensure this. This is done in +service of security, but also in service of code quality — code reviews are the +best way to ensure that code is secure, maintainable, and understandable. ### Dependencies -We keep all of our dependencies up to date. All of our repositories are expected -to use [Dependabot](https://dependabot.com/) to automatically open pull requests -for updates to our dependencies. +Dependencies are kept up to date. All repositories are expected to use +[Dependabot](https://dependabot.com/) to automatically open pull requests for +dependency updates. -All of our production code has 100% test coverage. We have automated tests in -place to ensure that changes do not break our application. Debugging or -non-production code is not required to have 100% test coverage. +All production code has 100% test coverage. Automated tests are in place to +ensure that changes do not break the application. Debugging or non-production +code is not required to have 100% test coverage. ### Deployment -All changes to production are deployed through a CI/CD pipeline. We use -[GitHub Actions](https://docs.github.com/en/actions) for this. We have a staging -environment that is used for testing changes before they are deployed to -production. +All changes to production are deployed through a CI/CD pipeline using +[GitHub Actions](https://docs.github.com/en/actions). A staging environment is +used for testing changes before they're deployed to production. -Our CI/CD pipeline runs tests, linters, and other checks before deploying to -production. Our CI/CD pipeline is configured with unique service accounts that -have the minimum permissions necessary to deploy to production. +The CI/CD pipeline runs tests, linters, and other checks before deploying to +production, and is configured with unique service accounts that have the minimum +permissions necessary to deploy to production. ### Rollbacks -We have the ability to roll back changes to production. Typically we execute a -roll back via a revert commit in our codebase and a new deployment; however, we -also have the ability to roll back individual services in our infrastructure to -previous versions if necessary. +Changes to production can be rolled back. Typically this is done via a revert +commit and a new deployment; however, individual services in the infrastructure +can also be rolled back to previous versions if necessary. ## Incident response -We have a private playbook for incident response. We have logging and alerting -in place to detect and respond to incidents. We have both dedicated private -channels on Discord for response as well as back-up text communication pathways -as well as phone numbers for all engineers. +Shorebird has a private playbook for incident response, with logging and +alerting in place to detect and respond to incidents. Dedicated private channels +on Discord are used for response, along with back-up text communication pathways +and phone numbers for all engineers. -We do not currently have separate incident tracking beyond our public GitHub. We -always notified all customers when affected by incidents (security or otherwise) -via their billing email address in the past and will continue to do so going -forward. +There is not currently separate incident tracking beyond Shorebird's public +GitHub. Customers affected by incidents (security or otherwise) have always been +notified via their billing email address, and this will continue going forward. ### Post-mortems -We have a post-mortem process in place for incidents. We prepare a post-mortem -for all incidents within 48 hours of their occurrence. We use these post-mortems -to improve our systems and processes. We do not currently share our post-mortems -publicly, although we are considering doing so in the future. +A post-mortem process is in place for incidents. A post-mortem is prepared for +all incidents within 48 hours of their occurrence and used to improve systems +and processes. Post-mortems are not currently shared publicly, although this is +being considered for the future. ## Data usage & security ### Data privacy -See our privacy policy: https://shorebird.dev/privacy +See the privacy policy: https://shorebird.dev/privacy -The information we collect from you is used to provide the service for you. We -do not sell or share your information with third parties, except as required by -law. Your data is stored in association with your account and deleted when you -delete your account. +The information collected from you is used to provide the service to you. It is +not sold or shared with third parties, except as required by law. Your data is +stored in association with your account and deleted when you delete your +account. Shorebird does not process, transmit, or store personally identifiable -information for our customers' end users. Additionally, we take care to store as -little data from our customers (you) as possible. +information for customers' end users, and takes care to store as little data +from customers (you) as possible. ### Data retention -We retain customer data for as long as you have an account with us. Customers -are able to access and delete their data at any time. We retain aggregated, -anonymized data for analytics purposes beyond termination of your account. +Customer data is retained for as long as you have an account with Shorebird. +Customers are able to access and delete their data at any time. Aggregated, +anonymized data is retained for analytics purposes beyond termination of your +account. Customers can delete almost all information in their account by hand; however, deleting the final database row requires contacting support at this time: https://docs.shorebird.dev/uninstall/ -See our privacy policy for more information: https://shorebird.dev/privacy +See the privacy policy for more information: https://shorebird.dev/privacy ### Data security @@ -249,88 +244,89 @@ as all data in Google Cloud) is encrypted at rest. https://cloud.google.com/docs/security/encryption-in-transit https://cloud.google.com/docs/security/encryption/default-encryption -We are not aware of any past data breaches of any form for Shorebird. In the -event of a breach, we will notify all customers promptly unless otherwise -required by local law enforcement. +Shorebird is not aware of any past data breaches of any form. In the event of a +breach, all customers will be notified promptly unless otherwise required by +local law enforcement. ### Data separation -Shorebird does not currently use per-tenant data storage. We use a single, -secured, non-publicly-reachable database (AlloyDB) for all system data. We use a -variety of private cloud buckets for storing customer data files, which are -segmented currently based on purpose rather than customer/tenant. +Shorebird does not currently use per-tenant data storage. It uses a single, +secured, non-publicly-reachable database (AlloyDB) for all system data, and a +variety of private cloud buckets for storing customer data files, currently +segmented by purpose rather than customer/tenant. -As noted elsewhere, we do not store _any_ information about your customers. +As noted elsewhere, Shorebird does not store _any_ information about your +customers. -Customer data we store for you is only your email addresses and the data files -you have created within our service. Stripe stores your billing information on -our behalf. +Customer data stored for you is limited to your email addresses and the data +files you have created within the service. Stripe stores your billing +information on Shorebird's behalf. ### Confidentiality -Our [Terms of Service](https://shorebird.dev/terms) and -[Privacy Policy](https://shorebird.dev/privacy) cover our obligations to you as -our customer. +Shorebird's [Terms of Service](https://shorebird.dev/terms) and +[Privacy Policy](https://shorebird.dev/privacy) cover its obligations to you as +a customer. #### Customer Data (data about you as a user of Shorebird) -In general, we do not access customer data unless required as part of providing +In general, customer data is not accessed unless required as part of providing you support or monitoring the service for usage and security. -We treat customer data as confidential. We have logging in place to detect -unauthorized access to customer data. Customer data may be accessed by employees -as part of providing support to you. +Customer data is treated as confidential, with logging in place to detect +unauthorized access. Customer data may be accessed by employees as part of +providing support to you. -We do not share customer data with third parties except as required by law. We -have a few third-party services that we use to run our business; see our privacy -policy for our list of vendors: https://shorebird.dev/privacy/ +Customer data is not shared with third parties except as required by law. A few +third-party services are used to run the business; see the privacy policy for +the list of vendors: https://shorebird.dev/privacy/ -We try to store very little data for or about our customers. Examples of -customer data we store include: +Very little data is stored for or about customers. Examples of customer data +stored include: - Email address and Name -- Stripe Customer ID (we do not store payment information) +- Stripe Customer ID (payment information is not stored) - Built applications archives (e.g., `.xcarchive`, `.aab` for Releases and Patches) - Release Metadata (e.g., Flutter version, Xcode version, Java version, etc.) Shorebird servers never see or store your source code. All `shorebird` commands run locally on devices you control and only upload the built application -archives (same binaries you distribute to stores and your users) to our servers -for your later use or distribution. +archives (same binaries you distribute to stores and your users) to Shorebird's +servers for your later use or distribution. Google Cloud encrypts all data at rest by default. #### End user data (data about Shorebird's customers' end users) _Shorebird does not process, transmit or store personally identifiable -information for our customers' end users. We do not have access to end user -data._ Customer security forms often ask for information about how we handle end -user data. We do not handle end user data. +information for customers' end users, and does not have access to end user +data._ Customer security forms often ask for information about how Shorebird +handles end user data — it does not handle end user data. Some regions consider IP addresses to be personally identifiable information, -Google Cloud does record IP addresses in logs. We do not access these IP -addresses in logs for any purpose other than security and monitoring. +Google Cloud does record IP addresses in logs. These IP addresses in logs are +not accessed for any purpose other than security and monitoring. Shorebird's product allows you, and only you, to update the code of your -application on end user devices. We do not collect or wish to collect any -information from these users or devices. +application on end user devices. Shorebird does not collect or wish to collect +any information from these users or devices. ## Third-party assessments -We have no third-party security, network, or other assessments to share at this -time. Some of our larger customers have performed their own audits of our -provided infrastructure and when appropriate we have made adjustments based on -their feedback. +Shorebird has no third-party security, network, or other assessments to share at +this time. Some larger customers have performed their own audits of the provided +infrastructure, and adjustments have been made based on their feedback when +appropriate. -As noted in other parts of this document, we intentionally do not run our own -servers, or build our own network infrastructure, rather we rely on Google and -Cloudflare servers and networks to reduce our total exposure and +As noted in other parts of this document, Shorebird intentionally does not run +its own servers or build its own network infrastructure, relying instead on +Google and Cloudflare servers and networks to reduce total exposure and upgrade/maintenance burdens. ## Bug bounty -We do not currently offer a bug bounty program. We welcome reports of security -vulnerabilities. Please see our +Shorebird does not currently offer a bug bounty program, but welcomes reports of +security vulnerabilities. Please see the [Vulnerability Management Policy](https://handbook.shorebird.dev/compliance/vulnerability-management-policy/) for more details. From e650b3337eef23a06cb82df43a66d517a2d942fa Mon Sep 17 00:00:00 2001 From: Tom Arra Date: Thu, 2 Jul 2026 14:53:40 -0500 Subject: [PATCH 02/13] docs: rewrite first-person voice in percentage-based-rollouts guide --- .../guides/percentage-based-rollouts.mdx | 44 +++++++++---------- 1 file changed, 22 insertions(+), 22 deletions(-) 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. Date: Thu, 2 Jul 2026 14:55:24 -0500 Subject: [PATCH 03/13] docs: rewrite first-person voice in CI FAQ --- src/content/docs/ci/faq.mdx | 52 ++++++++++++++++++------------------- 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/src/content/docs/ci/faq.mdx b/src/content/docs/ci/faq.mdx index 770e3a0a..55e5f4d9 100644 --- a/src/content/docs/ci/faq.mdx +++ b/src/content/docs/ci/faq.mdx @@ -14,10 +14,10 @@ for migration options. ::: -Still have a question about Shorebird CI that our docs didn’t cover? You’re in +Still have a question about Shorebird CI that the docs didn’t cover? You’re in the right place. This page covers the most common questions. If you have a question not answered here or elsewhere in the docs, reach out on Discord or -file an issue. We’re here to help. +file an issue. The Shorebird team is happy to help. ## Product overview @@ -44,57 +44,57 @@ CodeMagic, fastlane, etc.) but rather to supplement them. ### How fast is it? -Our checks typically complete in under a minute even with large repos, including -monorepos. This is mostly due to our caching of Dart & Flutter and automatic -parallelization of packages. We will continue to invest in this over time as we -see more usage and understand the communities needs when it comes to Dart -specific pipelines. +Checks typically complete in under a minute even with large repos, including +monorepos. This is mostly due to caching of Dart & Flutter and automatic +parallelization of packages. Shorebird will continue to invest in this over time +as usage grows and the community's needs around Dart-specific pipelines become +clearer. ### What checks are supported? -We are starting with a few key ones that we see our own need for and what other -open source repo's are doing. We will continue to keep our [Checks](/ci/checks/) -documentation up to date with what we currently have available. +Shorebird CI starts with a few key checks based on internal needs and what other +open source repos are doing. The [Checks](/ci/checks/) documentation will +continue to be kept up to date with what's currently available. If you have a specific check that you are looking for please don't hesitate to -reach out. We are always looking to implement more based on community needs. +reach out — more checks are always being considered based on community needs. ## GitHub Integration ### What GitHub permissions does this require and why? -In order to use Shorebird CI, our GitHub Application requires the following +In order to use Shorebird CI, its GitHub Application requires the following permissions -- **Read access to code, metadata, and pull requests** - This allows for our - application to checkout your codebase and run the necessary checks. All code +- **Read access to code, metadata, and pull requests** - This allows the + application to check out your codebase and run the necessary checks. All code is securely deleted after runs. - **Read and write access to checks, commit statuses, and workflows** - This - allows for our application to report back on the status checks that are - running and display them in the GitHub UI. + allows the application to report back on the status checks that are running + and display them in the GitHub UI. ## Data privacy ### Where do builds happen? -Builds are happening through our partnership with namespace.so. Namespace uses +Builds happen through Shorebird's partnership with namespace.so. Namespace uses several custom datacenters throughout the world and you can read more about this in their [Documentation Site](https://namespace.so/docs) and [Trust Center](https://trust.namespace.so). ### What data do you retain? -In order to provide a complete service we do need to retain some of your data. +In order to provide a complete service, some of your data needs to be retained. -- **Logs** - The only data we intentionally retain is your build logs, which are +- **Logs** - The only data intentionally retained is your build logs, which are served from - [the CI section of our web console](https://console.shorebird.dev/ci/). We - also maintain some minimal metadata to associate a pull request/commit with a + [the CI section of the web console](https://console.shorebird.dev/ci/). Some + minimal metadata is also maintained to associate a pull request/commit with a build log. - - Our build provider [Namespace](https://namespace.so), also does retain logs - in accordance with their [Terms of Use](https://namespace.so/terms). -- **Source Code** - We retain a copy of your public source code to speed up - repeated builds. We do not currently have an explicit retention time on this. + - Shorebird's build provider [Namespace](https://namespace.so) also retains + logs in accordance with their [Terms of Use](https://namespace.so/terms). +- **Source Code** - A copy of your public source code is retained to speed up + repeated builds. There is not currently an explicit retention time on this. Private repositories are currently under development and will have more stringent requirements. @@ -105,6 +105,6 @@ no additional information or data will be sent to Shorebird CI. Public log links are currently retained after an uninstall in order to not break links on existing PRs. If you require those to be deleted as well please reach -out to us +out [via email](mailto:contact@shorebird.dev?subject=CI%20Data%20Delete%20Request) from the account owners address and it will be handled manually. From 0a9c2b7bc6693a2603ab1d93cfd5f79633349d5a Mon Sep 17 00:00:00 2001 From: Tom Arra Date: Thu, 2 Jul 2026 14:57:45 -0500 Subject: [PATCH 04/13] docs: rewrite first-person voice in Android/iOS flavors guides --- .../docs/code-push/guides/flavors/android.mdx | 29 +++++++++---------- .../docs/code-push/guides/flavors/ios.mdx | 26 ++++++++--------- 2 files changed, 25 insertions(+), 30 deletions(-) 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 From 92f8a0c1738f426e62a5339b9d54c2ffe68bcdda Mon Sep 17 00:00:00 2001 From: Tom Arra Date: Thu, 2 Jul 2026 15:01:58 -0500 Subject: [PATCH 05/13] docs: rewrite first-person voice in billing, hybrid-apps, and testing guides --- src/content/docs/account/billing.mdx | 28 +++++------ .../docs/code-push/guides/hybrid-apps/ios.mdx | 28 +++++------ .../docs/code-push/guides/staging-patches.mdx | 24 +++++----- .../docs/code-push/guides/testing-patches.mdx | 46 +++++++++---------- 4 files changed, 62 insertions(+), 64 deletions(-) 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. ```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/testing-patches.mdx b/src/content/docs/code-push/guides/testing-patches.mdx index c2773958..dc8538a6 100644 --- a/src/content/docs/code-push/guides/testing-patches.mdx +++ b/src/content/docs/code-push/guides/testing-patches.mdx @@ -7,23 +7,23 @@ sidebar: import { LinkCard } from 'starlight-theme-nova/components'; -We recommend that you test your patches with a subset of users before -distributing to all users. +Testing your patches with a subset of users before distributing to all users is +recommended. Shorebird’s mechanism to release to a subset of users is “tracks”. You can create an unlimited number of tracks with arbitrary names. If no track is specified, patches are distributed to the “stable” track by default. -Typically we see customers use "staging" for internal testing (on developers' -machines) and "beta" for wider group testing (e.g. QA teams where `shorebird` -commands are not available). +Customers typically use "staging" for internal testing (on developers' machines) +and "beta" for wider group testing (e.g. QA teams where `shorebird` commands are +not available). -As part of our privacy stance, we _never_ know anything about your users, so we -have no way to tell users apart or to specify which users should receive a patch -from within our product. However, we do provide you mechanisms for controlling -updates via Shorebird with user information you have access to from within your -company and your application. See the Percentage Based Rollouts guide for -examples. +As part of Shorebird's privacy stance, it _never_ knows anything about your +users, so there is no way to tell users apart or to specify which users should +receive a patch from within the product. However, mechanisms are provided for +controlling updates via Shorebird with user information you have access to from +within your company and your application. See the Percentage Based Rollouts +guide for examples. -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. From 6af20700e49abdac8cb5a647e64f8978b589c88d Mon Sep 17 00:00:00 2001 From: Tom Arra Date: Thu, 2 Jul 2026 15:03:49 -0500 Subject: [PATCH 06/13] docs: rewrite first-person voice in troubleshooting guide --- .../docs/code-push/troubleshooting.mdx | 28 +++++++++---------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/src/content/docs/code-push/troubleshooting.mdx b/src/content/docs/code-push/troubleshooting.mdx index b185eb4f..fd2e50b2 100644 --- a/src/content/docs/code-push/troubleshooting.mdx +++ b/src/content/docs/code-push/troubleshooting.mdx @@ -7,8 +7,8 @@ sidebar: This page covers the most common issues with Shorebird Code Push. Still stuck? Reach out on [Discord](https://discord.gg/shorebird) or -[file an issue](https://github.com/shorebirdtech/shorebird/issues). We're here -to help. +[file an issue](https://github.com/shorebirdtech/shorebird/issues). The +Shorebird team is happy to help. ## Patch not showing up @@ -36,8 +36,8 @@ Sending patch check request: PatchCheckRequest { If the release version is the version you expect to see, check the [Shorebird Console](https://console.shorebird.dev) to ensure that this release -exists for the given app ID and that it has a patch. Please contact us on -Discord if such a patch exists and is not being applied. +exists for the given app ID and that it has a patch. Please reach out on Discord +if such a patch exists and is not being applied. Common issues: @@ -70,7 +70,7 @@ you create a patch for version `1.0.0+1`, it will not work on version `1.0.0+2`. This can happen unexpectedly on iOS due to Xcode's automatic incrementing of build numbers. If you are seeing this issue on iOS, ensure that the build number of the release and the patch match. See -[our iOS releasing guide](/code-push/guides/stores/app-store/#upload-to-the-app-store) +[the iOS releasing guide](/code-push/guides/stores/app-store/#upload-to-the-app-store) for instructions on how to disable automatic build number incrementing. ::: @@ -139,8 +139,9 @@ can happen if your app uses more or fewer icons from the Dart code. Flutter will automatically "tree shake" your fonts, so if you don't use an icon in your Dart code, it will not be included in the final app. You can disable this behavior with `--no-tree-shake-icons` at the risk of increasing your app size. This type -of warning will also go away once we add -[asset patching](https://github.com/shorebirdtech/shorebird/issues/318). +of warning will also go away once +[asset patching](https://github.com/shorebirdtech/shorebird/issues/318) is +added. A type of change not shown above is one which changes .dex files on Android or the `Runner.app` directory on iOS. These changes represent changes to the native @@ -149,7 +150,7 @@ you should be very careful about publishing your patch, as it may cause your app to crash when the Dart code tries to call into native code which operates differently than expected. -**What happens if I ignore this warning?** +**What happens if you ignore this warning?** You can bypass this warning by passing the `--allow-asset-diffs` flag to the `shorebird patch` command. @@ -182,7 +183,7 @@ solutions violate this assumption and can cause these native changes to appear. Shorebird may be incompatible with those plugins. You can test for this by doing a `shorebird release` and then `shorebird patch` with no changes and seeing if you still get a native changes warning. If you believe this is the case, please -reach out to us; we'd be happy to help. +reach out; the Shorebird team is happy to help. ::: @@ -224,7 +225,7 @@ This can be caused by a number of things. The most common causes are: implemented some safeguards to make this less likely, but it is worth verifying if you are seeing this warning and you do not know why. -**What happens if I ignore this warning?** +**What happens if you ignore this warning?** :::danger @@ -342,15 +343,14 @@ to check which Java version works with which Gradle release. ## Missing a provisioning profile or no signing team was found -We address this issue in our [releasing guide](/code-push/release). Take a look -at the iOS section for more information. +This issue is addressed in the [releasing guide](/code-push/release). Take a +look at the iOS section for more information. ## Message saying patch might run slowly iOS uses a very different patching process than Android does. The details of which are described in [System Architecture](/code-push/system-architecture/). -We also talk about this in our [Patch Performance](/code-push/performance/) -page. +This is also discussed in the [Patch Performance](/code-push/performance/) page. --- From e94d490491439ed659750ea8831157f65975a6bc Mon Sep 17 00:00:00 2001 From: Tom Arra Date: Thu, 2 Jul 2026 15:04:52 -0500 Subject: [PATCH 07/13] docs: rewrite first-person voice in App Store releasing guide --- .../code-push/guides/stores/app-store.mdx | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) 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: Date: Thu, 2 Jul 2026 15:07:34 -0500 Subject: [PATCH 08/13] docs: rewrite first-person voice in Codemagic CI guide --- src/content/docs/code-push/ci/codemagic.mdx | 36 ++++++++++----------- 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/src/content/docs/code-push/ci/codemagic.mdx b/src/content/docs/code-push/ci/codemagic.mdx index 651ee03a..03d7add4 100644 --- a/src/content/docs/code-push/ci/codemagic.mdx +++ b/src/content/docs/code-push/ci/codemagic.mdx @@ -64,15 +64,15 @@ distributed. :::note -We will be setting up our workflow using the Codemagic YAML file. The Workflow -Editor is not supported, as it does not allow us to change the build command. +This workflow uses the Codemagic YAML file. The Workflow Editor is not +supported, as it does not allow changing the build command. If you don't know how to use the Codemagic YAML, please refer to the [Codemagic YAML documentation](https://docs.codemagic.io/yaml-basic-configuration/yaml-getting-started/). ::: -As a preview, our finished `codemagic.yaml` file will look like this: +As a preview, the finished `codemagic.yaml` file will look like this: ```yaml definitions: @@ -146,15 +146,15 @@ workflows: You can follow the Codemagic guide [here](https://docs.codemagic.io/yaml-code-signing/signing-android/#google-play-store-credentials) -to set this up. We put the `GCLOUD_SERVICE_ACCOUNT_CREDENTIALS` variable in a -group named `play_store`. +to set this up. This example places the `GCLOUD_SERVICE_ACCOUNT_CREDENTIALS` +variable in a group named `play_store`. #### Set up your Android keystore in Codemagic You can follow the Codemagic guide [here](https://docs.codemagic.io/yaml-code-signing/signing-android/) to create a -keystore and upload it to Codemagic. We used `android_keystore` as the name of -the uploaded keystore. +keystore and upload it to Codemagic. This example uses `android_keystore` as the +name of the uploaded keystore. You will also also need to update your `android/app/build.gradle` file to use this keystore in the Codemagic CI environment: @@ -179,7 +179,7 @@ signingConfigs { ### Create shared configuration -At the top of our `codemagic.yaml` file, define shared environment variables and +At the top of the `codemagic.yaml` file, define shared environment variables and scripts that will be used by multiple workflows. This has been annotated to explain what each part does. @@ -303,8 +303,8 @@ distributed. :::note -We will be setting up our workflow using the Codemagic YAML file. The Workflow -Editor is not supported, as it does not allow us to change the build command. +This workflow uses the Codemagic YAML file. The Workflow Editor is not +supported, as it does not allow changing the build command. If you don't know how to use the Codemagic YAML, please refer to the [Codemagic YAML documentation](https://docs.codemagic.io/yaml-basic-configuration/yaml-getting-started/). @@ -337,11 +337,11 @@ support this: of this file into Codemagic. `cat ios_distribution_private_key | pbcopy` works well for this. -We put all of these variables into a group named `app_store`. +This example places all of these variables into a group named `app_store`. ### Create a shared configuration -At the top of our `codemagic.yaml` file, define shared environment variables and +At the top of the `codemagic.yaml` file, define shared environment variables and scripts that will be used by multiple workflows. This has been annotated to explain what each part does. @@ -406,8 +406,8 @@ definitions: keychain add-certificates - &use_profiles # This generates an export_options.plist file that tells Xcode - # how to package our app. We explicitly set - # manageAppVersionAndBuildNumber so that we can control which + # how to package the app. This explicitly sets + # manageAppVersionAndBuildNumber to control which # version and build number are used for releasing and patching. name: Set up code signing settings on Xcode project script: | @@ -430,11 +430,11 @@ workflows: # This needs to run on a Mac instance. instance_type: mac_mini_m1 integrations: - # "Codemagic" is the name of our App Store Connect API key name. + # "Codemagic" is the name of the App Store Connect API key. app_store_connect: Codemagic environment: <<: *shared_env - # Tell Codemagic that we're signing our app for App Store distribution + # Tell Codemagic that this app is being signed for App Store distribution # and to use the bundle ID we defined above. ios_signing: distribution_type: app_store @@ -481,8 +481,8 @@ workflows: instance_type: mac_mini_m1 environment: <<: *shared_env - # Tell Codemagic that we're signing our app for App Store distribution - # and to use the bundle ID we defined above. + # Tell Codemagic that this app is being signed for App Store distribution + # and to use the bundle ID defined above. ios_signing: distribution_type: app_store bundle_identifier: '$BUNDLE_ID' From 20d78cf1c0ae0efc7a2246cb6a3f9a345d37f719 Mon Sep 17 00:00:00 2001 From: Tom Arra Date: Thu, 2 Jul 2026 15:09:14 -0500 Subject: [PATCH 09/13] docs: rewrite first-person voice in advanced state management guide --- .../state-management/advanced.mdx | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) 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. From 155a96b9f3962510eb5e35e26602f5479264ad31 Mon Sep 17 00:00:00 2001 From: Tom Arra Date: Thu, 2 Jul 2026 15:14:57 -0500 Subject: [PATCH 10/13] docs: rewrite first-person voice in Play Store, generic CI, and GitHub CI guides --- src/content/docs/code-push/ci/generic.mdx | 19 +++++++++---------- src/content/docs/code-push/ci/github.mdx | 9 ++++----- .../code-push/guides/stores/play-store.mdx | 16 ++++++++-------- 3 files changed, 21 insertions(+), 23 deletions(-) diff --git a/src/content/docs/code-push/ci/generic.mdx b/src/content/docs/code-push/ci/generic.mdx index 76af6c9d..e2e97aba 100644 --- a/src/content/docs/code-push/ci/generic.mdx +++ b/src/content/docs/code-push/ci/generic.mdx @@ -19,7 +19,7 @@ Flutter CI builds. Changes required: 3. Replacing `flutter build --release` with `shorebird release` or `shorebird patch`. -We have detailed instructions for integrating into these providers: +Detailed instructions are available for integrating into these providers: -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. Date: Thu, 2 Jul 2026 15:16:23 -0500 Subject: [PATCH 11/13] docs: rewrite first-person voice in Android hybrid, performance, and Flutter SDK guides --- .../code-push/guides/hybrid-apps/android.mdx | 12 +++++----- src/content/docs/code-push/performance.mdx | 23 ++++++++++--------- .../flutter-sdk-deep-dive.mdx | 16 ++++++------- 3 files changed, 25 insertions(+), 26 deletions(-) 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/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/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. From f08310c0792d6860301a47f1e265f99028194050 Mon Sep 17 00:00:00 2001 From: Tom Arra Date: Thu, 2 Jul 2026 15:19:47 -0500 Subject: [PATCH 12/13] docs: rewrite first-person voice in development workflow, security tools, fastlane, symbols, release, rollback, update-strategies, architecture-trees, and flutter-version guides --- src/content/docs/code-push/ci/fastlane.mdx | 10 +++++----- .../crash-reporting/uploading-symbols.mdx | 13 ++++++------- .../code-push/guides/development-workflow.mdx | 18 +++++++++--------- .../docs/code-push/guides/security-tools.mdx | 12 ++++++------ src/content/docs/code-push/release.mdx | 8 ++++---- src/content/docs/code-push/rollback.mdx | 8 ++++---- .../docs/code-push/update-strategies.mdx | 12 ++++++------ .../flutter-concepts/architecture-trees.mdx | 14 +++++++------- .../docs/getting-started/flutter-version.mdx | 14 +++++++------- 9 files changed, 54 insertions(+), 55 deletions(-) diff --git a/src/content/docs/code-push/ci/fastlane.mdx b/src/content/docs/code-push/ci/fastlane.mdx index c9f1d4de..91500975 100644 --- a/src/content/docs/code-push/ci/fastlane.mdx +++ b/src/content/docs/code-push/ci/fastlane.mdx @@ -23,7 +23,7 @@ This section assumes that you are using fastlane on CI to release your app. If you are running fastlane locally (on your development machine), you can skip to the [Using fastlane locally](#using-fastlane-locally). -A working example of this setup can be found in our +A working example of this setup can be found in the [fastlane_demo](https://github.com/shorebirdtech/fastlane_demo) repository. To get started, follow @@ -31,10 +31,10 @@ To get started, follow to set up fastlane with certificate management, code signing, and submitting to the App Store/TestFlight. -You will notice that our demo app's +Notice that the demo app's [`Fastfile`](https://github.com/shorebirdtech/fastlane_demo/blob/main/ios/fastlane/Fastfile) has both `deploy` and `release_shorebird` lanes. The `deploy` lane comes from -the guide linked to above. The `release_shorebird` lane is our custom lane that +the guide linked to above. The `release_shorebird` lane is a custom lane that uses the `shorebird_release` action **in place of** `build_app` to build an ipa, create a Shorebird release, and submit it to the App Store/TestFlight. @@ -59,8 +59,8 @@ installed Shorebird, you can do so by following the If you are not already using fastlane with your project, navigate to your app's `ios` directory in your project and run `fastlane init`. You will be prompted to -answer several questions. For this guide, we will choose to manually add lanes -to the `Fastfile`. +answer several questions. For this guide, choose to manually add lanes to the +`Fastfile`. ### Use the Shorebird plugin diff --git a/src/content/docs/code-push/crash-reporting/uploading-symbols.mdx b/src/content/docs/code-push/crash-reporting/uploading-symbols.mdx index e6ed5220..21e89dc8 100644 --- a/src/content/docs/code-push/crash-reporting/uploading-symbols.mdx +++ b/src/content/docs/code-push/crash-reporting/uploading-symbols.mdx @@ -5,13 +5,13 @@ sidebar: order: 12 --- -Shorebird uses a fork of Flutter to build your app. This means we've built our -own copy of Flutter's engine which means that the symbols included in the -Flutter.framework or libflutter.so are slightly different from the upstream +Shorebird uses a fork of Flutter to build your app. This means Shorebird has +built its own copy of Flutter's engine, which means that the symbols included in +the Flutter.framework or libflutter.so are slightly different from the upstream Flutter engine. -If you would like to see C++ symbols from our fork of Flutter's engine in your -crash reports, you will need to upload the symbols to your crash reporting tool. +To see C++ symbols from Shorebird's fork of Flutter's engine in your crash +reports, upload the symbols to your crash reporting tool. Google provides instructions for how to integrate various crash reporting tools into your Flutter app: @@ -44,8 +44,7 @@ Flutter 3.32.5 • revision 44a8ada33bdbe7f25a49e7dcf13c5c1f648129fd Engine • revision f275acddf709f94ef38af54adb2c1a0a0a90b5c6 ``` -In this case, we're using `f275acddf709f94ef38af54adb2c1a0a0a90b5c6` as the -engine hash. +In this case, `f275acddf709f94ef38af54adb2c1a0a0a90b5c6` is the engine hash. ## Symbols for iOS diff --git a/src/content/docs/code-push/guides/development-workflow.mdx b/src/content/docs/code-push/guides/development-workflow.mdx index 724757f5..3c38e4e7 100644 --- a/src/content/docs/code-push/guides/development-workflow.mdx +++ b/src/content/docs/code-push/guides/development-workflow.mdx @@ -14,7 +14,7 @@ import releaseWorkflow from '~/assets/release_workflow.png'; import patchWorkflow from '~/assets/patch_workflow.png'; This guide will walk you through an opinionated development workflow with -Shorebird. We'll cover how to automate releasing and patching with Shorebird to +Shorebird, covering how to automate releasing and patching with Shorebird to streamline the entire development process so that you and your team can focus on shipping high-quality features to customers. @@ -34,7 +34,7 @@ to your customers, but it's up to you to decide how to integrate it into your development workflow. While there are many ways to integrate Shorebird, the following workflow is a -common approach that we recommend: +common recommended approach: Development Workflow @@ -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/security-tools.mdx b/src/content/docs/code-push/guides/security-tools.mdx index 6715ef5d..bd77bfe8 100644 --- a/src/content/docs/code-push/guides/security-tools.mdx +++ b/src/content/docs/code-push/guides/security-tools.mdx @@ -99,17 +99,17 @@ thus send a _different_ version of your application to users, Shorebird will be unable to create a compatible patch for your users since they will be using a different binary than you stored with Shorebird. -Other than the "it must be during the build" restriction, we've seen few issues -with third party security tools and Shorebird. +Other than the "it must be during the build" restriction, few issues have been +seen with third party security tools and Shorebird. ### GuardSquare on iOS -We have seen one issue with GuardSquare on iOS with Shorebird. GuardSquare (at +One issue has been seen with GuardSquare on iOS with Shorebird. GuardSquare (at least in some configurations) will make an attempt to "obfuscate" iOS binaries further, replacing the implementations of some functions with code which is used to provide obscured access to constants/strings/numbers stored within the binary. This may be incompatible with Shorebird's Dart modifications for iOS. If -this is an issue for your product, we'd be happy to discuss with the GuardSquare -support team if there are workarounds we could build together. +this is an issue for your product, the Shorebird team is happy to discuss with +the GuardSquare support team if there are possible workarounds. -Reach out to us at contact@shorebird.dev. +Reach out at contact@shorebird.dev. 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: Date: Thu, 2 Jul 2026 15:22:10 -0500 Subject: [PATCH 13/13] docs: rewrite first-person voice in remaining account, CI, code-push, and getting-started pages --- src/content/docs/account/api-keys.mdx | 6 +++--- src/content/docs/account/orgs.mdx | 2 +- src/content/docs/ci/checks/index.mdx | 3 +-- src/content/docs/ci/index.mdx | 4 ++-- .../docs/code-push/guides/patch-signing.mdx | 18 +++++++++--------- .../docs/code-push/guides/white-labeling.mdx | 10 +++++----- src/content/docs/code-push/index.mdx | 2 +- src/content/docs/code-push/patch.mdx | 2 +- src/content/docs/code-push/uninstall.mdx | 4 ++-- .../flutter-concepts/flutter-for-beginners.mdx | 12 ++++++------ src/content/docs/getting-started/index.mdx | 2 +- src/content/docs/index.mdx | 2 +- src/content/docs/system/status.mdx | 2 +- 13 files changed, 34 insertions(+), 35 deletions(-) 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/orgs.mdx b/src/content/docs/account/orgs.mdx index 644102f9..f74416f4 100644 --- a/src/content/docs/account/orgs.mdx +++ b/src/content/docs/account/orgs.mdx @@ -25,7 +25,7 @@ via the account settings page in the [Shorebird console](https://console.shorebird.dev/account). If you do not see the plan you're expecting, please reach out to -contact@shorebird.dev, and we'd be happy to help you. +contact@shorebird.dev for help. ## Creating an organization diff --git a/src/content/docs/ci/checks/index.mdx b/src/content/docs/ci/checks/index.mdx index c3cd8b2c..b81ad57a 100644 --- a/src/content/docs/ci/checks/index.mdx +++ b/src/content/docs/ci/checks/index.mdx @@ -13,7 +13,6 @@ for migration options. ::: Shorebird CI contains a number of checks built into the system. With each run -all of our checks are automatically ran with no need for setup from you or your -team. +all checks are automatically ran with no need for setup from you or your team. For details on each check please view the detail pages. diff --git a/src/content/docs/ci/index.mdx b/src/content/docs/ci/index.mdx index 0be1091b..e827a39f 100644 --- a/src/content/docs/ci/index.mdx +++ b/src/content/docs/ci/index.mdx @@ -20,8 +20,8 @@ for migration options. Zero-config, production-grade continuous integration for Flutter & Dart. Shorebird CI automatically runs best practice Flutter & Dart checks on every -pull request. We built it for ourselves and use it in all our repos, and now you -can too. +pull request. The Shorebird team built it for themselves and uses it in all of +Shorebird's repos, and now you can too. - ✨ Set up takes less than a minute - 🚀 Fast Checks 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/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/uninstall.mdx b/src/content/docs/code-push/uninstall.mdx index fd8be672..5e58cdbf 100644 --- a/src/content/docs/code-push/uninstall.mdx +++ b/src/content/docs/code-push/uninstall.mdx @@ -13,10 +13,10 @@ disabled at any time with no effect on your users. ## Thank you Thank you for trying Shorebird. If you'd like to continue using Shorebird but -have questions or concerns, please reach out to us on Discord or via email at +have questions or concerns, please reach out on Discord or via email at [contact@shorebird.dev](mailto:contact@shorebird.dev). -Otherwise, we hope you'll consider trying Shorebird again in the future. +Otherwise, consider trying Shorebird again in the future. ## Uninstalling Shorebird diff --git a/src/content/docs/flutter-concepts/flutter-for-beginners.mdx b/src/content/docs/flutter-concepts/flutter-for-beginners.mdx index b2a04c39..1e3fd841 100644 --- a/src/content/docs/flutter-concepts/flutter-for-beginners.mdx +++ b/src/content/docs/flutter-concepts/flutter-for-beginners.mdx @@ -258,9 +258,9 @@ Here's what the app will look like on an Android device: 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/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: