From b41b7223236cc6cf23a7fd010eef403c59fdb9aa Mon Sep 17 00:00:00 2001 From: Tom Arra Date: Thu, 2 Jul 2026 12:16:09 -0500 Subject: [PATCH 1/3] docs: use sentence case for headers Per the marketing content guidelines, headers should use sentence case, not Title Case. Fixes 169 headings across 44 files. Left several categories of heading untouched, all confirmed by testing directly against Vale rather than guessing: - Compound product/brand names where per-word exception matching breaks down and partially-casing the phrase reads worse than the original: "Azure Key Vault", "GCP Cloud KMS", "App Store Connect", "Firebase Remote Config", "Launch Darkly", "Flutter Hot Reload". - Three "Flutter vs. X" headings: Vale's capitalization rule flags any heading containing "vs"/"vs." regardless of surrounding case, a hardcoded quirk that isn't configurable via the exceptions list. - Four "code push" FAQ headings (e.g. "Does code push require the internet to work?"): enabling the Vocab-driven proper-noun rule causes Vale's capitalization rule to also flag any lowercase vocab term (Shorebird/Flutter/Code Push) in a heading, even though sentence case itself has no violation here. These already get fixed by the proper-noun-capitalization PR; no separate edit needed here. - Three sequential numbered headings ("1. The Status Enum", "2. The Single State Class", "3. The Events"): Vale's algorithm inexplicably passes #2 once lowercased but keeps flagging #1 and #3 with identical structure. Reverted all three to Title Case to keep the numbered list visually consistent rather than partially complying. Also discovered and fixed real proper nouns that weren't yet recognized by the Headings rule's exceptions list (Stripe, Fastfile, BuildContext, RenderObject, Apple, 1Password, AOT, GuardSquare, LTS, ExportOptions.plist, Skia, Impeller) and two headings using lowercase "fastlane" where the tool name should be capitalized ("Using Fastlane on CI/locally"). These exceptions need to land in the tooling PR (#576) as well, or they'll show as false positives again once these two PRs both merge. Co-Authored-By: Claude Sonnet 5 --- src/content/docs/account/api-keys.mdx | 6 +-- src/content/docs/account/billing.mdx | 12 +++--- src/content/docs/account/cli.mdx | 12 +++--- src/content/docs/account/orgs.mdx | 24 +++++------ src/content/docs/ci/checks/analyze.mdx | 2 +- src/content/docs/ci/checks/check-spelling.mdx | 2 +- src/content/docs/ci/checks/format.mdx | 2 +- src/content/docs/ci/checks/run-tests.mdx | 2 +- .../docs/ci/checks/upload-coverage.mdx | 2 +- src/content/docs/ci/faq.mdx | 4 +- src/content/docs/ci/index.mdx | 2 +- src/content/docs/code-push/ci/codemagic.mdx | 4 +- src/content/docs/code-push/ci/fastlane.mdx | 4 +- src/content/docs/code-push/ci/generic.mdx | 2 +- src/content/docs/code-push/ci/github.mdx | 6 +-- .../crash-reporting/uploading-symbols.mdx | 2 +- src/content/docs/code-push/faq.mdx | 16 +++---- .../code-push/guides/development-workflow.mdx | 6 +-- .../docs/code-push/guides/flavors/android.mdx | 6 +-- .../docs/code-push/guides/flavors/ios.mdx | 4 +- .../docs/code-push/guides/hybrid-apps/ios.mdx | 2 +- .../docs/code-push/guides/patch-signing.mdx | 14 +++---- .../docs/code-push/guides/security-tools.mdx | 4 +- .../docs/code-push/guides/staging-patches.mdx | 2 +- src/content/docs/code-push/index.mdx | 2 +- src/content/docs/code-push/initialize.mdx | 2 +- src/content/docs/code-push/patch.mdx | 16 +++---- src/content/docs/code-push/performance.mdx | 2 +- src/content/docs/code-push/preview.mdx | 6 +-- src/content/docs/code-push/release.mdx | 16 +++---- src/content/docs/code-push/rollback.mdx | 2 +- .../docs/code-push/system-architecture.mdx | 20 ++++----- .../docs/code-push/update-strategies.mdx | 2 +- .../flutter-concepts/architecture-trees.mdx | 12 +++--- .../complete-introduction-flutter.mdx | 18 ++++---- .../flutter-for-beginners.mdx | 4 +- .../flutter-sdk-deep-dive.mdx | 4 +- .../how-to-install-flutter.mdx | 4 +- .../state-management/advanced.mdx | 18 ++++---- .../state-management/beginner.mdx | 6 +-- .../docs/getting-started/flutter-version.mdx | 8 ++-- src/content/docs/getting-started/index.mdx | 6 +-- src/content/docs/index.mdx | 6 +-- src/content/docs/system/security.mdx | 42 +++++++++---------- 44 files changed, 169 insertions(+), 169 deletions(-) diff --git a/src/content/docs/account/api-keys.mdx b/src/content/docs/account/api-keys.mdx index f22d894c..66eb9d7a 100644 --- a/src/content/docs/account/api-keys.mdx +++ b/src/content/docs/account/api-keys.mdx @@ -11,7 +11,7 @@ API keys let you authenticate with Shorebird from CI systems and other automated environments. You can create, view, and revoke API keys from the [Shorebird Console](https://console.shorebird.dev). -## Creating an API Key +## Creating an API key 1. Open **Account → API Keys** in the console. 2. Click **Create API Key**. @@ -28,7 +28,7 @@ securely — it cannot be retrieved again. title="Create Shorebird API Key" /> -## Using an API Key +## Using an API key Set the key as the `SHOREBIRD_TOKEN` environment variable in your CI platform. Shorebird CLI commands will authenticate automatically when this variable is @@ -64,7 +64,7 @@ API keys support two permission levels: manage apps, organizations, members, or billing. Available on Pro and Business plans. -## Revoking an API Key +## Revoking an API key To revoke a key, find it in the API Keys list and click **Delete**. Revocation is immediate — any CI pipeline using that key will fail on its next run. This diff --git a/src/content/docs/account/billing.mdx b/src/content/docs/account/billing.mdx index b039fea3..148f2455 100644 --- a/src/content/docs/account/billing.mdx +++ b/src/content/docs/account/billing.mdx @@ -15,13 +15,13 @@ 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. -## Payment Provider - Stripe +## 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 [Stripe's Supported Payment Methods documentation](https://docs.stripe.com/payments/payment-methods/overview). -### Billing Email +### Billing email Invoices are sent at the end of each billing period by Stripe. Since they are sent by Stripe, they do not use your Shorebird account email, but rather the @@ -40,7 +40,7 @@ log in, you can change this in Stripe: This will open Stripe's billing portal, where you can update your Stripe email, which is where invoices are sent. -## Available Plans +## 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 @@ -52,7 +52,7 @@ 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). -### Organizations & Billing +### Organizations & billing Billing is tied to the **organization's owner's account**, not to individual organizations. When you create an organization, it inherits its plan from your @@ -62,7 +62,7 @@ each organization will share the owner's plan. For more information on how organizations and ownership work, see [Organizations](/account/orgs#billing--ownership). -## How We Bill +## How we bill Shorebird charges based on successful patch installs. A “patch install” is a successful update applied on a customer’s device. @@ -77,7 +77,7 @@ You can view your current patch installs in [your account page](https://console.shorebird.dev/account) on the Shorebird Console. These numbers are updated hourly. -### Overage Billing +### Overage billing For our monthly plans, we offer optional overage billing. This is turned off by default. diff --git a/src/content/docs/account/cli.mdx b/src/content/docs/account/cli.mdx index af099c86..6067164e 100644 --- a/src/content/docs/account/cli.mdx +++ b/src/content/docs/account/cli.mdx @@ -11,7 +11,7 @@ The Shorebird CLI provides several commands to help you manage your authentication state, inspect your account details, and list your apps and organizations directly from the terminal. -## Authentication Commands +## Authentication commands ### Login @@ -35,12 +35,12 @@ from your machine, run: shorebird logout ``` -## Account Management Commands +## Account management commands The `shorebird account` command provides several subcommands to inspect your account details, apps, and organizations. -### Who Am I +### Who am I To see the currently authenticated user's details, run: @@ -61,7 +61,7 @@ Overage limit: 10000 This command is useful for verifying which account you are logged into and checking your current billing plan and patch overage limit. -### List Apps +### List apps To list all the Shorebird apps that your current account has access to, run: @@ -79,7 +79,7 @@ shorebird account apps The output displays the App ID, display name, latest release version, and latest patch number (with `-` indicating no release or patch has been published yet). -### List Organizations +### List organizations To list all the organizations you belong to, run: @@ -99,7 +99,7 @@ This output displays the Organization ID, name, organization type (`personal` or --- -## JSON Output for Automation +## JSON output for automation All `shorebird account` subcommands support the `--json` flag, making them easy to integrate into scripts and automation workflows. diff --git a/src/content/docs/account/orgs.mdx b/src/content/docs/account/orgs.mdx index 11e9b7f0..644102f9 100644 --- a/src/content/docs/account/orgs.mdx +++ b/src/content/docs/account/orgs.mdx @@ -17,7 +17,7 @@ Organizations are a way to share groups of apps with people. This is useful for any team collaborating across a company to have access as needed to releases, patches, and more. -## Account Requirements +## Account requirements Shorebird's paid plans unlock features for collaborating with your peers. Shorebird's free plan users can upgrade to a paid plan to access these features @@ -27,7 +27,7 @@ via the account settings page in the 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. -## Creating an Organization +## Creating an organization To create an organization, visit the Shorebird console and click the account dropdown in the top left corner. From there, click the "+" button next to @@ -47,13 +47,13 @@ the name. alt="Screenshot of how to get to Organization settings in the Shorebird Console" /> -## Managing Apps +## Managing apps Organizations can have multiple apps associated with them. You can either transfer existing apps to an organization or create new apps within the organization directly. -### Create a New App +### Create a new app To create a new app within an organization, select the organization when running `shorebird init`: @@ -63,7 +63,7 @@ To create a new app within an organization, select the organization when running alt="Screenshot of doing `shorebird init` command and selecting an organization" /> -### Transfer an App +### Transfer an app To transfer an existing app to an organization, visit the app's settings and click the "Transfer app" button. You can then select the organization you want @@ -74,9 +74,9 @@ to transfer the app to from the dropdown. alt="Screenshot of dialog for transferring app to a different org in the Shorebird Console" /> -## Managing Members +## Managing members -### Add a Member +### Add a member To add one or more members to your organization, visit the organization's settings and click the "Add member" button. @@ -94,13 +94,13 @@ same organization settings page. alt="Screenshot of successfully adding a member to an Organization in the Shorebird Console" /> -### Remove a Member +### Remove a member You can easily remove a member from an organization via the organization's settings page. Locate the member you wish to remove, click the Trash icon, and confirm the action. -## Member Roles +## Member roles Organization roles apply to all apps within the organization and can be managed via the organization settings page in the Shorebird console. The roles available @@ -126,7 +126,7 @@ Hands-on role for engineers actively building and shipping apps. Can create releases and patches, promote patches, and manage day-to-day development workflows without administrative access. -### App Manager +### App manager Responsible for managing application lifecycle and release strategy. Has all Developer capabilities plus elevated control over app-level configuration, @@ -143,7 +143,7 @@ excluding billing and plan changes. Full control over the organization. Can manage billing and plans, ownership settings, and all platform capabilities. Intended for primary account holders. -## Billing & Ownership +## Billing & ownership Each organization has a single owner. An organization's plan is determined by its [owner's](#owner) subscription. Their Shorebird subscription is what sets @@ -153,7 +153,7 @@ To manage billing, the organization owner can visit the [billing settings](https://console.shorebird.dev/account) in the Shorebird console. See [Billing](/account/billing) for more details. -## Managing Per App Collaborators +## Managing per app collaborators Per-app collaborators can also be added and managed via the Shorebird console. The same management and permissions structure of organizations applies to diff --git a/src/content/docs/ci/checks/analyze.mdx b/src/content/docs/ci/checks/analyze.mdx index e23e7180..a49b9f52 100644 --- a/src/content/docs/ci/checks/analyze.mdx +++ b/src/content/docs/ci/checks/analyze.mdx @@ -23,7 +23,7 @@ None. As long as your repository has Dart code detected this check will run. If you have an `analysis_options.yaml` file with customizations, they are recognized during this check. -## Available Statuses +## Available statuses ### Pass diff --git a/src/content/docs/ci/checks/check-spelling.mdx b/src/content/docs/ci/checks/check-spelling.mdx index a4527ec8..05e5bfd2 100644 --- a/src/content/docs/ci/checks/check-spelling.mdx +++ b/src/content/docs/ci/checks/check-spelling.mdx @@ -22,7 +22,7 @@ more information on this please consult the [Getting Started in CSpell Docs](https://cspell.org/docs/getting-started#1-create-a-configuration-file) for details. -## Available Statuses +## Available statuses ### Pass diff --git a/src/content/docs/ci/checks/format.mdx b/src/content/docs/ci/checks/format.mdx index 1d413ae6..cf2b768a 100644 --- a/src/content/docs/ci/checks/format.mdx +++ b/src/content/docs/ci/checks/format.mdx @@ -23,7 +23,7 @@ None. As long as your repository has Dart code detected this check will run. If you have an `analysis_options.yaml` file with customizations, they are recognized during this check. -## Available Statuses +## Available statuses ### Pass diff --git a/src/content/docs/ci/checks/run-tests.mdx b/src/content/docs/ci/checks/run-tests.mdx index d8ef81b6..bdbddb7a 100644 --- a/src/content/docs/ci/checks/run-tests.mdx +++ b/src/content/docs/ci/checks/run-tests.mdx @@ -20,7 +20,7 @@ they are passing. None. As long as your repository has Dart or Flutter tests detected this check will run. -## Available Statuses +## Available statuses ### Pass diff --git a/src/content/docs/ci/checks/upload-coverage.mdx b/src/content/docs/ci/checks/upload-coverage.mdx index fc0520a0..7df81e6e 100644 --- a/src/content/docs/ci/checks/upload-coverage.mdx +++ b/src/content/docs/ci/checks/upload-coverage.mdx @@ -23,7 +23,7 @@ more information on this please consult the [Codecov YAML documentation](https://docs.codecov.com/docs/codecov-yaml) for details. -## Available Statuses +## Available statuses ### Pass diff --git a/src/content/docs/ci/faq.mdx b/src/content/docs/ci/faq.mdx index 4b804aad..770e3a0a 100644 --- a/src/content/docs/ci/faq.mdx +++ b/src/content/docs/ci/faq.mdx @@ -19,7 +19,7 @@ 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. -## Product Overview +## Product overview ### Why should I use this rather then another solution? @@ -73,7 +73,7 @@ permissions allows for our application to report back on the status checks that are running and display them in the GitHub UI. -## Data Privacy +## Data privacy ### Where do builds happen? diff --git a/src/content/docs/ci/index.mdx b/src/content/docs/ci/index.mdx index 9b06f223..9aaca9bb 100644 --- a/src/content/docs/ci/index.mdx +++ b/src/content/docs/ci/index.mdx @@ -40,7 +40,7 @@ can too! > -## Requirements for Use +## Requirements for use Shorebird CI will work on any repository that contains at least one Flutter or Dart project, including monorepos. diff --git a/src/content/docs/code-push/ci/codemagic.mdx b/src/content/docs/code-push/ci/codemagic.mdx index 6d6fbade..651ee03a 100644 --- a/src/content/docs/code-push/ci/codemagic.mdx +++ b/src/content/docs/code-push/ci/codemagic.mdx @@ -20,7 +20,7 @@ on how to integrate with Shorebird. ::: -# Codemagic Workflow Integration +# Codemagic workflow integration This guide will help you integrate Shorebird into your Codemagic Workflow using the @@ -177,7 +177,7 @@ signingConfigs { } ``` -### Create Shared Configuration +### Create shared configuration At the top of our `codemagic.yaml` file, define shared environment variables and scripts that will be used by multiple workflows. This has been annotated to diff --git a/src/content/docs/code-push/ci/fastlane.mdx b/src/content/docs/code-push/ci/fastlane.mdx index f586eac8..7ec7d846 100644 --- a/src/content/docs/code-push/ci/fastlane.mdx +++ b/src/content/docs/code-push/ci/fastlane.mdx @@ -17,7 +17,7 @@ Follow the setup instructions on the fastlane website to install fastlane ([ios](https://docs.fastlane.tools/getting-started/ios/setup/), [android](https://docs.fastlane.tools/getting-started/android/setup/)). -## Using fastlane on CI +## Using Fastlane on CI 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 @@ -47,7 +47,7 @@ To patch your app, you can use the `shorebird_patch` action. You can see an example of this in the `patch_shorebird` lane in the [`Fastfile`](https://github.com/shorebirdtech/fastlane_demo/blob/main/ios/fastlane/Fastfile#L92-L98). -## Using fastlane locally +## Using Fastlane locally ### Setup diff --git a/src/content/docs/code-push/ci/generic.mdx b/src/content/docs/code-push/ci/generic.mdx index 08b00553..f48704b4 100644 --- a/src/content/docs/code-push/ci/generic.mdx +++ b/src/content/docs/code-push/ci/generic.mdx @@ -113,7 +113,7 @@ a patch is a set of changes to apply to a Release. you're trying to patch. `shorebird` will look up the exact version of Flutter used to build the release and use that exact version to build the patch. -## CI Best Practices +## CI best practices When integrating Shorebird into a continuous integration pipeline, we recommend following these best practices to ensure reliable and efficient builds: diff --git a/src/content/docs/code-push/ci/github.mdx b/src/content/docs/code-push/ci/github.mdx index 1edacab6..6c5915fc 100644 --- a/src/content/docs/code-push/ci/github.mdx +++ b/src/content/docs/code-push/ci/github.mdx @@ -26,7 +26,7 @@ Refer to the [getting started](/) instructions for more information. ::: -## Quick Start +## Quick start To integrate Shorebird into your CI, use the `setup-shorebird` action. The `setup-shorebird` action downloads Shorebird and adds it to the system path. @@ -88,7 +88,7 @@ secret: Now we can use the `SHOREBIRD_TOKEN` in our GitHub workflow to perform authenticated functions such as creating patches 🎉 -## Create Releases +## Create releases The simplest way to create a release is using the official Shorebird GitHub Actions: @@ -152,7 +152,7 @@ The `shorebird-release` action also outputs the release version: ::: -## Create Patches +## Create patches ```yaml name: Shorebird Patch 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 f58c2727..e6ed5220 100644 --- a/src/content/docs/code-push/crash-reporting/uploading-symbols.mdx +++ b/src/content/docs/code-push/crash-reporting/uploading-symbols.mdx @@ -18,7 +18,7 @@ into your Flutter app: https://docs.flutter.dev/cookbook/maintenance/error-reporting -# Getting Symbols from the Console +# Getting symbols from the console Shorebird's console provides links to download the symbols for both for your built app and the Flutter engine in the "Artifacts" tab of the release page. diff --git a/src/content/docs/code-push/faq.mdx b/src/content/docs/code-push/faq.mdx index 13e865cc..9ea46ac4 100644 --- a/src/content/docs/code-push/faq.mdx +++ b/src/content/docs/code-push/faq.mdx @@ -12,7 +12,7 @@ have a question not answered here or elsewhere in the docs, reach out on [file an issue](https://github.com/shorebirdtech/shorebird/issues). We're here to help. -## Getting Started +## Getting started ### What is the difference between a patch and a release? @@ -83,7 +83,7 @@ Yes. The `shorebird` command line tool passes through all Dart defines to the work as expected. Because Dart defines are compiled into your app's Dart code, they can be updated via patches. -### How do I target different API environments (e.g., Staging vs. Production backend) for patches? +### How do I target different API environments (e.g., staging vs. production backend) for patches? You should use Flutter flavors (or `--dart-define` config variables). Shorebird fully supports flavors. @@ -144,7 +144,7 @@ to test iOS patches. _Note: Android emulators are fully supported._ -### Does Shorebird work in Debug or Profile mode? +### Does Shorebird work in debug or profile mode? No. Shorebird is only compiled into and active in **Release builds** of your application. @@ -197,7 +197,7 @@ Steps to upgrade: Any future patches created for this new release version will automatically be built using the upgraded Flutter version. -## Store Compliance +## Store compliance ### Does Shorebird comply with Play Store guidelines? @@ -299,7 +299,7 @@ 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. -## Use Cases & Limitations +## Use cases & limitations ### What can I use Shorebird code push for? @@ -399,7 +399,7 @@ the latest version from the server if needed. If you have a use case for code push with Fluter web, we'd [love to know](mailto:contact@shorebird.dev)! -## Technical Details +## Technical details ### What does the Shorebird updater store on disk? @@ -535,7 +535,7 @@ as long as newer patches also contain the changes from older patches, users will always be up to date and there is no need to worry about users "missing" patches. -## Teams, Access, and Privacy +## Teams, access, and privacy ### Can I use Shorebird with my team? @@ -619,7 +619,7 @@ Shorebird is not itself a store. Your users will need to install your app initially through some method other than Shorebird, but Shorebird can then be used to patch (update) your app after that initial install. -### How does Shorebird interact with Play Testing Tracks or Apple TestFlight? +### How does Shorebird interact with Play testing tracks or Apple TestFlight? Each of the app stores have separate mechanisms for distributing apps to limited groups of users (e.g. "internal testing", "closed beta", etc.). These are all diff --git a/src/content/docs/code-push/guides/development-workflow.mdx b/src/content/docs/code-push/guides/development-workflow.mdx index 698aa5a4..724757f5 100644 --- a/src/content/docs/code-push/guides/development-workflow.mdx +++ b/src/content/docs/code-push/guides/development-workflow.mdx @@ -52,7 +52,7 @@ The workflow consists of three main phases: Let's walk through each phase in more detail. -## Development Phase +## Development phase During this phase, developers are building features and fixing bugs. @@ -77,7 +77,7 @@ You can refer to the following GitHub Actions workflow for an example. -## Release Phase +## Release phase When the team is ready to distribute a new version of the app, a release is created. In some cases, releases are created on a regular cadence (e.g., weekly, @@ -249,7 +249,7 @@ For more information about configuring signing refer to the following links: ::: -## Patch Phase +## Patch phase Even with great testing, sometimes bugs can creep into the app. Shorebird allows you to fix these bugs and distribute the patches to customers' devices diff --git a/src/content/docs/code-push/guides/flavors/android.mdx b/src/content/docs/code-push/guides/flavors/android.mdx index 8c57b8f0..90836931 100644 --- a/src/content/docs/code-push/guides/flavors/android.mdx +++ b/src/content/docs/code-push/guides/flavors/android.mdx @@ -20,7 +20,7 @@ that you are logged into an account. Refer to the [getting started](https://docs.shorebird.dev/getting-started/) instructions for more information. -## Create a Project +## Create a project :::note @@ -32,7 +32,7 @@ ahead. Create a new project using `shorebird create flavors`. -## Configure Flavors +## Configure flavors @@ -342,7 +342,7 @@ flavors: + beta: a41f8226-4b46-45d6-9e19-b14d0cf17bdc ``` -## Multi-dimensional Flavors +## Multi-dimensional flavors For an example that uses multi-dimensional flavors, see the [multi_dimensional_flavors](https://github.com/shorebirdtech/samples/tree/main/multi_dimensional_flavors) diff --git a/src/content/docs/code-push/guides/flavors/ios.mdx b/src/content/docs/code-push/guides/flavors/ios.mdx index 4590dbdf..4909d7a3 100644 --- a/src/content/docs/code-push/guides/flavors/ios.mdx +++ b/src/content/docs/code-push/guides/flavors/ios.mdx @@ -20,7 +20,7 @@ that you are logged into an account. Refer to the [getting started](https://docs.shorebird.dev/getting-started/) instructions for more information. -## Create a Project +## Create a project :::note @@ -32,7 +32,7 @@ ahead. Create a new project using `shorebird create flavors`. -## Configure Flavors +## Configure flavors Next, edit the iOS project to support two flavors: `internal` and `stable` by following the instructions in the diff --git a/src/content/docs/code-push/guides/hybrid-apps/ios.mdx b/src/content/docs/code-push/guides/hybrid-apps/ios.mdx index 92e3faae..d5c11c1b 100644 --- a/src/content/docs/code-push/guides/hybrid-apps/ios.mdx +++ b/src/content/docs/code-push/guides/hybrid-apps/ios.mdx @@ -113,7 +113,7 @@ signature. ::: -### Add the path to your .xcframeworks to Framework Search Paths +### Add the path to your .xcframeworks to framework search paths In Xcode: diff --git a/src/content/docs/code-push/guides/patch-signing.mdx b/src/content/docs/code-push/guides/patch-signing.mdx index f861081c..0494a83d 100644 --- a/src/content/docs/code-push/guides/patch-signing.mdx +++ b/src/content/docs/code-push/guides/patch-signing.mdx @@ -32,7 +32,7 @@ application. You will need an RSA key pair. Shorebird supports RSA keys in PEM format, both PKCS#1 and PKCS#8. -### Generate Keys +### Generate keys If you do not already have an RSA key pair you'd like to use, you can generate a pair with `openssl`: @@ -58,7 +58,7 @@ stored securely and kept secret. While the private key is not itself sufficient to make an update to your application (someone would also need access to your Shorebird credentials), it should not be checked into public source control. -### Key Storage +### 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 @@ -78,7 +78,7 @@ greater to use this feature. See [Cloud KMS Examples](#cloud-kms-examples) below for integration examples with popular services. -### Create a Signed Release +### Create a signed release :::note @@ -101,7 +101,7 @@ shorebird release android \ This will include the public key in the release artifact produced by `shorebird release` and cause the released app to require signed patches. -### Create a Signed Patch +### Create a signed patch To create a signed patch, run the following command: @@ -121,7 +121,7 @@ shorebird patch android --public-key-path /path/to/public.pem \ This tells Shorebird to sign the patch with the key pair you provided. -### Test and Verify Signed Patch +### Test and verify signed patch You can verify that the patch is properly signed using `shorebird preview`. On the first launch, you should see something like the following in your app logs: @@ -148,7 +148,7 @@ If you'd like to test the missing signature behavior, you can create a patch without a private key and notice that `shorebird preview` rejects it. Similarly, you can create a patch with a different private key to do the same. -## Fallback Behavior +## Fallback behavior Releases that contain a public key will reject all unsigned patches. If a patch is missing a signature or its signature is invalid, Shorebird will reject this @@ -165,7 +165,7 @@ 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. -## Cloud KMS Examples +## Cloud KMS examples The following examples show how to integrate Shorebird patch signing with popular key management services using `--public-key-cmd` and `--sign-cmd`. diff --git a/src/content/docs/code-push/guides/security-tools.mdx b/src/content/docs/code-push/guides/security-tools.mdx index 9274282f..6715ef5d 100644 --- a/src/content/docs/code-push/guides/security-tools.mdx +++ b/src/content/docs/code-push/guides/security-tools.mdx @@ -43,7 +43,7 @@ may be a more reliable approach for those use-cases since obfuscation tools might not find all the ways in which your company secrets could be encoded in your binary. -## Flutter & Dart built-in Obfuscation +## Flutter & Dart built-in obfuscation Flutter (via Dart) supports basic obfuscation out of the box. @@ -78,7 +78,7 @@ shorebird patch ios an older version of Flutter, `shorebird release --obfuscate` will display an error asking you to upgrade. ::: -## Third Party Security Programs +## Third party security programs There are a variety of third party security programs for mobile. The vast majority of these work fine with Shorebird. diff --git a/src/content/docs/code-push/guides/staging-patches.mdx b/src/content/docs/code-push/guides/staging-patches.mdx index 9b87458e..54d34a22 100644 --- a/src/content/docs/code-push/guides/staging-patches.mdx +++ b/src/content/docs/code-push/guides/staging-patches.mdx @@ -19,7 +19,7 @@ This guide assumes the Shorebird command-line is installed on your machine and that you are logged into an account. Refer to the [getting started](/) instructions for more information. -## Create a Project +## Create a project :::note diff --git a/src/content/docs/code-push/index.mdx b/src/content/docs/code-push/index.mdx index fe106e3c..9cdbe778 100644 --- a/src/content/docs/code-push/index.mdx +++ b/src/content/docs/code-push/index.mdx @@ -65,7 +65,7 @@ For a quick overview, check out the demo below. title="Send over the air updates to Flutter app" /> -### Platform Feature Support Matrix +### Platform feature support matrix Below is a summary of feature support status across all Shorebird target platforms: diff --git a/src/content/docs/code-push/initialize.mdx b/src/content/docs/code-push/initialize.mdx index 255b2ec3..602bdb0c 100644 --- a/src/content/docs/code-push/initialize.mdx +++ b/src/content/docs/code-push/initialize.mdx @@ -172,7 +172,7 @@ by re-initializing shorebird. ::: -## What's Next +## What's next -### Patching Multiple Platforms Simultaneously +### Patching multiple platforms simultaneously If your app supports multiple platforms, you can build and publish patches for them in a single command using the `--platforms` (or `-p`) option: @@ -145,7 +145,7 @@ directly. | `--allow-asset-diffs` | | Publish even if asset differences are detected. **Not recommended.** | | `--allow-native-diffs` | | Publish even if native code differences are detected. **Not recommended.** | -### iOS-specific Options +### iOS-specific options | Option | Description | | ------------------------ | ------------------------------------------------------------------------------------------------ | @@ -154,7 +154,7 @@ directly. | `--export-method` | Distribution method: `app-store`, `ad-hoc`, `development`, or `enterprise`. | | `--min-link-percentage` | Minimum % of Dart code that must be linked (not interpreted) for the patch to publish. iOS only. | -### Patch Performance +### Patch performance #### Android @@ -180,12 +180,12 @@ If you ever see unexpected performance changes when patching, please --- -## Manage Patches +## Manage patches You can manage your patches directly from the command line using the `shorebird patches` commands. -### List Patches +### List patches To list all patches associated with a specific release version: @@ -196,7 +196,7 @@ shorebird patches list --release-version 1.0.0+1 This will display a list of all patches published for that release, their patch numbers, active status, and tracks. -### View Patch Details +### View patch details To view detailed information for a specific patch number: @@ -207,7 +207,7 @@ shorebird patches info --release-version 1.0.0+1 --patch-number 1 This command shows metadata for the specified patch, including build logs, checksums, and deployment track information. -### Promote a Patch +### Promote a patch If you published a patch to a staging track (e.g., `staging`) and verified it works correctly, you can promote it directly to the `stable` track using: @@ -216,7 +216,7 @@ works correctly, you can promote it directly to the `stable` track using: shorebird patches promote --release-version 1.0.0+1 --patch-number 1 ``` -### Set Patch Track +### Set patch track To assign a patch directly to a specific deployment track (e.g., promoting or routing to a staging beta group): diff --git a/src/content/docs/code-push/performance.mdx b/src/content/docs/code-push/performance.mdx index 4c93e418..c04b3729 100644 --- a/src/content/docs/code-push/performance.mdx +++ b/src/content/docs/code-push/performance.mdx @@ -86,7 +86,7 @@ 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 +### Avoiding performance changes in iOS patches Unfortunately there is currently no good way to predict if a patch will cause a performance change to your application. diff --git a/src/content/docs/code-push/preview.mdx b/src/content/docs/code-push/preview.mdx index 7a4814c5..4b9c9114 100644 --- a/src/content/docs/code-push/preview.mdx +++ b/src/content/docs/code-push/preview.mdx @@ -37,7 +37,7 @@ useful for verifying releases that were created on a CI/CD server. | `--track` | | The deployment track to preview (e.g., `stable`, `staging`). Defaults to `stable`. | | `--app-id` | | The Shorebird app ID. Inferred from `shorebird.yaml` if not specified. | -### Android Keystore Options +### Android keystore options When previewing an Android release with a production keystore (instead of a debug key): @@ -73,7 +73,7 @@ from Xcode or Android Studio _with a Release configuration_, you will see Shorebird logs in its output. If you have published a patch, it should be downloaded on the first run of your app and visible on subsequent runs. -## Previewing Patches +## Previewing patches You can also use `shorebird preview` to test patches locally before publishing them to production. This is highly recommended to verify your Dart changes and @@ -108,7 +108,7 @@ To test a patch locally: :::tip For programmatic checks or showing custom update prompts, see the [Update Strategies](/code-push/update-strategies) guide. ::: -## What's Next +## What's next -### View Release Details +### View release details To view detailed information for a specific release version: @@ -490,7 +490,7 @@ shorebird releases get-apks --release-version 1.0.0+1 This will download the release artifacts and extract the compatible APK files to your machine. -### Delete Releases +### Delete releases :::danger @@ -536,7 +536,7 @@ shorebird release android --artifact=apk That will produce _both_ .apk and .aab files. You can distribute either or both as needed. -## What's Next +## What's next { } ``` -### Step 7: Main Entry Point and Observer Configuration +### Step 7: main entry point and observer configuration Wire repositories and observation logic globally inside your `main.dart`. @@ -657,7 +657,7 @@ class AppBlocObserver extends BlocObserver { --- -## Why Enterprise Teams Choose BLoC +## Why enterprise teams choose BLoC BLoC isn't popular because it is trendy; it sticks because it makes app behavior extremely predictable. When the codebase grows, and production issues happen diff --git a/src/content/docs/flutter-concepts/state-management/beginner.mdx b/src/content/docs/flutter-concepts/state-management/beginner.mdx index c6d27a6f..1a70d43a 100644 --- a/src/content/docs/flutter-concepts/state-management/beginner.mdx +++ b/src/content/docs/flutter-concepts/state-management/beginner.mdx @@ -27,7 +27,7 @@ fetching updates. This guide outlines the recommended approach for structuring BLoC using the **Single State pattern**. -## Core Architecture +## Core architecture **BLoC (Business Logic Component)** separates the UI layer from the business logic, promoting testability and predictability. The architecture follows a @@ -45,7 +45,7 @@ unidirectional data flow: alt="Diagram of how BLoC interacts with widgets and APIs" /> -## Handling Multiple State Classes +## Handling multiple state classes A common introductory pattern is defining separate classes for each state: @@ -74,7 +74,7 @@ transitions to `UserLoading`. Because `UserLoading` does not contain the typically results in the screen clearing entirely to show a loading spinner, creating a jarring user experience. -## Recommended Approach: The Single State Pattern +## Recommended approach: the single state pattern To maintain context during state transitions, it is recommended to use a single state class combined with a status enum and a `copyWith` method. This allows the diff --git a/src/content/docs/getting-started/flutter-version.mdx b/src/content/docs/getting-started/flutter-version.mdx index 94014da0..26ed85ed 100644 --- a/src/content/docs/getting-started/flutter-version.mdx +++ b/src/content/docs/getting-started/flutter-version.mdx @@ -13,7 +13,7 @@ When Shorebird CLI is installed, it pulls down the latest stable version of Shorebird's Flutter. In this section, we'll take a look at how to list and change the Flutter version used by Shorebird CLI. -## Supported Flutter Versions +## Supported Flutter versions | Platform | Minimum Flutter Version | Minimum Shorebird Version | | -------- | ----------------------- | ------------------------- | @@ -27,7 +27,7 @@ Shorebird recommends using the latest stable version of Flutter whenever possible. When we make changes to Shorebird, we do not currently backport those changes to previous releases of Flutter. -## List Flutter Versions +## List Flutter versions To list all Flutter versions Shorebird has published, use the `shorebird flutter versions list` command. @@ -41,7 +41,7 @@ Another way to see the current Flutter version is by running ::: -## Use a Different Flutter Version +## Use a different Flutter version By default, Shorebird will use the latest stable version of Flutter. If you need to create a release with a different version of Flutter, you can use the @@ -61,7 +61,7 @@ always be built with the version of Flutter used by the release. ::: -## Flutter Version Notes +## Flutter version notes To help you avoid hidden pitfalls, we maintain version notes on Flutter releases that have known issues affecting releasing apps or patching. Check here before diff --git a/src/content/docs/getting-started/index.mdx b/src/content/docs/getting-started/index.mdx index 17c853b3..929e156a 100644 --- a/src/content/docs/getting-started/index.mdx +++ b/src/content/docs/getting-started/index.mdx @@ -186,7 +186,7 @@ Flutter app. -## Keeping Shorebird Up To Date +## Keeping Shorebird up to date To update your local Shorebird CLI to the latest version, run: @@ -205,7 +205,7 @@ You can also see your current version at any time by running ::: -## Sample Apps +## Sample apps If you want to see Shorebird in action in a production-like application, check out our samples: @@ -216,7 +216,7 @@ out our samples: description="A professional, enterprise-grade Flutter architecture designed for Logic-Level Hotfixes." /> -## Next Steps +## Next steps -## Explore the Docs +## Explore the docs -## Contact Us +## Contact us Still have questions? Reach us through any of these channels. diff --git a/src/content/docs/system/security.mdx b/src/content/docs/system/security.mdx index 0461a89e..2cee39f1 100644 --- a/src/content/docs/system/security.mdx +++ b/src/content/docs/system/security.mdx @@ -29,7 +29,7 @@ Shorebird only offers a hosted service at this time. We do not currently offer [on-prem or cloud-prem](https://github.com/shorebirdtech/shorebird/issues/485) solutions. -### Company Security Policy +### Company security policy 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, @@ -43,7 +43,7 @@ Throughout this document, we will refer to the following terms: - Customer / you: A user of Shorebird. - End User: A user of a Customer's application. -## Acceptable Use +## Acceptable use Use of Shorebird is governed by our [Terms of Service](https://shorebird.dev/terms). We have logging and alerting in @@ -71,7 +71,7 @@ infrastructure are similar. We have written more on the architecture of Shorebird in our [architecture documentation](/code-push/system-architecture/). -### Shorebird Servers +### Shorebird servers `shorebird` tools communicate with Shorebird's cloud on your behalf. Shorebird exclusively uses public cloud infrastructure and does not maintain our own @@ -97,7 +97,7 @@ Because all access is done via HTTPS to public cloud infrastructure, typically no specific access rules are required to access Shorebird servers from within a company network. -### Product Access Control +### 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 @@ -106,7 +106,7 @@ our users. Shorebird accounts provide role-based access control on a per-application basis, which is described in our [Organizations product documentation](/account/orgs/). -### Production Access +### 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. @@ -118,7 +118,7 @@ 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. -### Network Access +### 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 @@ -135,13 +135,13 @@ Only the https port should be needed for access to Shorebird. See also https://docs.shorebird.dev/faq/#can-i-use-shorebird-in-my-country. -### User Access Review +### User access review We review all user access to our systems 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 +### 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 @@ -151,16 +151,16 @@ 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. -#### Intrusion Detection / Prevention / Monitoring +#### 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. -## Change Management +## Change management -### Code Reviews +### 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 @@ -196,7 +196,7 @@ 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. -## Incident Response +## 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 @@ -208,16 +208,16 @@ 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. -### Post-Mortems +### 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. -## Data Usage & Security +## Data usage & security -### Data Privacy +### Data privacy See our privacy policy: https://shorebird.dev/privacy @@ -230,7 +230,7 @@ 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. -### Data Retention +### 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, @@ -242,7 +242,7 @@ https://docs.shorebird.dev/uninstall/ See our privacy policy for more information: https://shorebird.dev/privacy -### Data Security +### Data security Shorebird uses Google Cloud's managed services for backups. This data (as well as all data in Google Cloud) is encrypted at rest. @@ -253,7 +253,7 @@ 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. -### Data Separation +### 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 @@ -301,7 +301,7 @@ 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) +#### 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 @@ -316,7 +316,7 @@ 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. -## Third-Party Assessments +## 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 @@ -328,7 +328,7 @@ servers, or build our own network infrastructure, rather we rely on Google and Cloudflare servers and networks to reduce our total exposure and upgrade/maintenance burdens. -## Bug Bounty +## Bug bounty We do not currently offer a bug bounty program. We welcome reports of security vulnerabilities. Please see our From 34275a84668c1ce4fe043679471b3ba208c394c9 Mon Sep 17 00:00:00 2001 From: Tom Arra Date: Thu, 2 Jul 2026 14:04:24 -0500 Subject: [PATCH 2/3] fix comments --- src/content/docs/flutter-concepts/architecture-trees.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/docs/flutter-concepts/architecture-trees.mdx b/src/content/docs/flutter-concepts/architecture-trees.mdx index 67410ff4..87e8363a 100644 --- a/src/content/docs/flutter-concepts/architecture-trees.mdx +++ b/src/content/docs/flutter-concepts/architecture-trees.mdx @@ -33,7 +33,7 @@ graph TD style R fill:#fff3e0,stroke:#ff9800,stroke-width:2px,color:#000 ``` -## 1. the widget tree: your blueprints +## 1. The widget tree: your blueprints Widgets are what you write every day: `Container`, `Text`, `Row`, `Column`, and so on. @@ -50,7 +50,7 @@ When you call `setState()`, you aren’t directly telling the screen to redraw. You are just telling Flutter to throw away the old stale objects and create new ones from the blueprints you created. -## 2. the element tree: the state manager +## 2. The element tree: the state manager If widgets are just temporary blueprints, how does Flutter remember anything? How does it keep track of an animation playing, or what you typed into a text @@ -77,7 +77,7 @@ This is the secret to Flutter's speed. The Element Tree manages the lifecycle and acts as the smart middleman that decides when actual heavy lifting needs to be done. -## 3. the RenderObject tree: the workhorse +## 3. The RenderObject tree: the workhorse Finally, we have the **RenderObject Tree**. From 694c5c94113fa7790d57ee997b4e7aecb1df72ea Mon Sep 17 00:00:00 2001 From: Tom Arra Date: Thu, 2 Jul 2026 14:05:05 -0500 Subject: [PATCH 3/3] fix comments --- src/content/docs/code-push/guides/hybrid-apps/ios.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/code-push/guides/hybrid-apps/ios.mdx b/src/content/docs/code-push/guides/hybrid-apps/ios.mdx index 73f5ae1c..b3c37b3b 100644 --- a/src/content/docs/code-push/guides/hybrid-apps/ios.mdx +++ b/src/content/docs/code-push/guides/hybrid-apps/ios.mdx @@ -113,7 +113,7 @@ signature. ::: -### Add the path to your .xcframeworks to framework search paths +### Add the path to your .xcframeworks to Framework Search Paths In Xcode: