From 6dd13013977b74669f6eac66d3fde93a367a7b24 Mon Sep 17 00:00:00 2001
From: Bryan Oltman <bryan@shorebird.dev>
Date: Thu, 4 May 2023 13:42:59 -0400
Subject: [PATCH 01/26] docs: minor copy edits to initialize.md

---
 docs/code_push/initialize.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/code_push/initialize.md b/docs/code_push/initialize.md
index 113b9555..40e70cae 100644
--- a/docs/code_push/initialize.md
+++ b/docs/code_push/initialize.md
@@ -6,10 +6,10 @@ description: Learn how to add code push to an existing Flutter project.
 
 # Initialize Shorebird
 
-To configure an existing Flutter project, to use Shorebird, use `shorebird init`
+To configure an existing Flutter project to use Shorebird, use `shorebird init`
 at the root of a Flutter project:
 
-```
+```sh
 shorebird init
 ```
 
@@ -22,15 +22,15 @@ This does three things:
    to Shorebird servers to identify which application to pull updates for.
    `app_id`s do not need to be kept secret.
 1. Adds the `shorebird.yaml` to the assets section of your `pubspec.yaml` file,
-   ensuring `shorebird.yaml` is bundled into your app's assets and available to
-   configure the Shorebird updater when your app runs.
+   ensuring `shorebird.yaml` is bundled with your app's assets and is available
+   to the Shorebird updater at runtime.
 
 You can safely commit these changes, they will have no affect on your app
 when not using Shorebird.
 
-Example output:
+Example output for an existing app named `shorebird_test`:
 
-```
+```sh
 $ shorebird init
 ? How should we refer to this app? (shorebird_test) shorebird_test
 ✓ Initialized Shorebird (38ms)

From f671a9025d658511033506e87c45a4af44a45d5b Mon Sep 17 00:00:00 2001
From: Bryan Oltman <bryan@shorebird.dev>
Date: Thu, 4 May 2023 17:42:29 -0400
Subject: [PATCH 02/26] docs: adds code push quickstart guide

---
 docs/quickstart.md | 154 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 154 insertions(+)
 create mode 100644 docs/quickstart.md

diff --git a/docs/quickstart.md b/docs/quickstart.md
new file mode 100644
index 00000000..949c4d27
--- /dev/null
+++ b/docs/quickstart.md
@@ -0,0 +1,154 @@
+---
+sidebar_position: 1
+title: ☄️ Quickstart
+description: How to create a new Shorebird app.
+---
+
+# Code Push Quickstart
+
+This guide shows you the fastest way to get started with Code Push.
+
+## Sign up
+
+Before you can create a Shorebird app, you will need to sign up for Shorebird.
+
+### Create an account
+
+To register as a Shorebird user, run:
+
+```sh
+shorebird account create
+```
+
+This will generate a Google sign in link. Follow the link and sign in with your
+Google account.
+
+### Subscribe
+
+Code push is currently only available to paid subscribers. To subscribe, run:
+
+```sh
+shorebird account subscribe
+```
+
+This will generate a payment Stripe payment link. Follow the link and enter your
+payment information.
+
+Subscriptions are $20/month. You can cancel at any time.
+
+## Create the app
+
+Once you have registered and subscribed, you're ready to use Shorebird!
+
+Start by creating a new Flutter app:
+
+```sh
+flutter create shorebird_app
+```
+
+As with any Flutter app, you can verify this created the standard Counter app by
+following the instructions printed by `flutter create`:
+
+```sh
+cd shorebird_app
+flutter run
+```
+
+### Initialize Shorebird
+
+To make this a Shorebird app, run:
+
+```sh
+shorebird init
+```
+
+This will create a `shorebird.yaml` file in the root of your project. This file
+contains your Shorebird `app_id`.
+
+Run `shorebird doctor` to ensure everything is set up correctly:
+
+```sh
+shorebird doctor
+```
+You will notice that this prints an error:
+
+```sh
+[✗] android/app/src/main/AndroidManifest.xml is missing the INTERNET permission.
+```
+
+This is because Shorebird requires the internet permission to download patches.
+You can fix this issue by running:
+
+```sh
+shorebird doctor --fix
+```
+
+### Run the app with Shorebird
+
+To run the app with Shorebird (that is, with [Shorebird's fork of the Flutter
+engine](/faq#how-does-shorebird-relate-to-flutter)), run:
+
+```sh
+shorebird run
+```
+
+Now kill the app on your device or emulator.
+
+### Create a release
+
+We will create a release using the unmodified Counter app. Run:
+
+```sh
+shorebird release
+```
+
+When prompted, use the suggested version number (`1.0.0+1`), and enter `y` when
+asked if you would like to continue.
+
+### Create a patch
+
+We will now make a small change to the Counter app. In `lib/main.dart`, change
+the app theme's `primarySwatch` from blue to green:
+
+```diff
+class MyApp extends StatelessWidget {
+  const MyApp({super.key});
+
+  // This widget is the root of your application.
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp(
+      title: 'Flutter Demo',
+      theme: ThemeData(
+        // This is the theme of your application.
+        //
+        // Try running your application with "flutter run". You'll see the
+        // application has a blue toolbar. Then, without quitting the app, try
+        // changing the primarySwatch below to Colors.green and then invoke
+        // "hot reload" (press "r" in the console where you ran "flutter run",
+        // or simply save your changes to "hot reload" in a Flutter IDE).
+        // Notice that the counter didn't reset back to zero; the application
+        // is not restarted.
+-       primarySwatch: Colors.blue,
++       primarySwatch: Colors.green,
+      ),
+      home: const MyHomePage(title: 'Flutter Demo Home Page'),
+    );
+  }
+}
+```
+
+After making this change, save the file and run:
+
+```sh
+shorebird patch
+```
+
+When prompted, use the suggested release version (`1.0.0+1`), and enter `y` when
+asked if you'd like to continue.
+
+### See the patch in action
+
+Launch the app from your device or emulator. The app will still have the
+original blue theme, but it will be downloading the patch we just created in the
+background. Kill and launch the app again, and the app will be green! 🎉

From c43223716870854c3d6f9b56b3767b640042f099 Mon Sep 17 00:00:00 2001
From: Bryan Oltman <bryanoltman@gmail.com>
Date: Wed, 17 May 2023 22:23:59 -0400
Subject: [PATCH 03/26] format

---
 docs/quickstart.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/quickstart.md b/docs/quickstart.md
index 949c4d27..7472dd9b 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -70,6 +70,7 @@ Run `shorebird doctor` to ensure everything is set up correctly:
 ```sh
 shorebird doctor
 ```
+
 You will notice that this prints an error:
 
 ```sh

From 48539749b21b3b85588007e01bd0abcf7b467b62 Mon Sep 17 00:00:00 2001
From: Bryan Oltman <bryanoltman@gmail.com>
Date: Wed, 17 May 2023 22:52:58 -0400
Subject: [PATCH 04/26] Move quickstart to tutorials section

---
 docs/tutorials/_category_.json                        | 11 +++++++++++
 .../code_push_quickstart.md}                          |  8 +++++---
 2 files changed, 16 insertions(+), 3 deletions(-)
 create mode 100644 docs/tutorials/_category_.json
 rename docs/{quickstart.md => tutorials/code_push_quickstart.md} (93%)

diff --git a/docs/tutorials/_category_.json b/docs/tutorials/_category_.json
new file mode 100644
index 00000000..d782c91f
--- /dev/null
+++ b/docs/tutorials/_category_.json
@@ -0,0 +1,11 @@
+{
+    "label": "🎓 Tutorials",
+    "position": 2,
+    "link": {
+      "title": "Tutorials",
+      "slug": "tutorials",
+      "type": "generated-index",
+      "description": "A collection of guides that help you get the most out of Shorebird."
+    }
+  }
+  
\ No newline at end of file
diff --git a/docs/quickstart.md b/docs/tutorials/code_push_quickstart.md
similarity index 93%
rename from docs/quickstart.md
rename to docs/tutorials/code_push_quickstart.md
index 7472dd9b..c73fc96f 100644
--- a/docs/quickstart.md
+++ b/docs/tutorials/code_push_quickstart.md
@@ -1,12 +1,14 @@
 ---
 sidebar_position: 1
-title: ☄️ Quickstart
-description: How to create a new Shorebird app.
+title: ☄️ Code Push Quickstart
+description: Try code push for yourself
 ---
 
 # Code Push Quickstart
 
-This guide shows you the fastest way to get started with Code Push.
+This guide shows you the fastest way to install Shorebird and try code push.
+
+This document is a (slightly) condensed version of our [code push](../code_push/) docs, all on one page.
 
 ## Sign up
 

From 973868bf9d2f38e8e06f09ff70579c0e0c53bd6b Mon Sep 17 00:00:00 2001
From: Bryan Oltman <bryanoltman@gmail.com>
Date: Thu, 18 May 2023 09:53:22 -0400
Subject: [PATCH 05/26] format

---
 docs/tutorials/_category_.json | 17 ++++++++---------
 1 file changed, 8 insertions(+), 9 deletions(-)

diff --git a/docs/tutorials/_category_.json b/docs/tutorials/_category_.json
index d782c91f..8d4175fa 100644
--- a/docs/tutorials/_category_.json
+++ b/docs/tutorials/_category_.json
@@ -1,11 +1,10 @@
 {
-    "label": "🎓 Tutorials",
-    "position": 2,
-    "link": {
-      "title": "Tutorials",
-      "slug": "tutorials",
-      "type": "generated-index",
-      "description": "A collection of guides that help you get the most out of Shorebird."
-    }
+  "label": "🎓 Tutorials",
+  "position": 2,
+  "link": {
+    "title": "Tutorials",
+    "slug": "tutorials",
+    "type": "generated-index",
+    "description": "A collection of guides that help you get the most out of Shorebird."
   }
-  
\ No newline at end of file
+}

From 3995ff442842ae66b358c181ffcf0950402e0159 Mon Sep 17 00:00:00 2001
From: Bryan Oltman <bryanoltman@gmail.com>
Date: Thu, 18 May 2023 09:54:38 -0400
Subject: [PATCH 06/26] update positions

---
 docs/architecture.md           | 2 +-
 docs/faq.md                    | 2 +-
 docs/status.md                 | 2 +-
 docs/tutorials/_category_.json | 2 +-
 docs/uninstall.md              | 2 +-
 5 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/docs/architecture.md b/docs/architecture.md
index c0a2b1b5..f382c02c 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 5
+sidebar_position: 6
 title: 🏛️ Architecture
 description: How Shorebird works.
 ---
diff --git a/docs/faq.md b/docs/faq.md
index 534b175b..ba484bf9 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 4
+sidebar_position: 5
 title: ❓ FAQ
 description: Frequently asked questions.
 ---
diff --git a/docs/status.md b/docs/status.md
index 817912c8..ed165e12 100644
--- a/docs/status.md
+++ b/docs/status.md
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 3
+sidebar_position: 4
 title: 👷 Status
 description: Status of the Shorebird project.
 ---
diff --git a/docs/tutorials/_category_.json b/docs/tutorials/_category_.json
index 8d4175fa..5395c2c4 100644
--- a/docs/tutorials/_category_.json
+++ b/docs/tutorials/_category_.json
@@ -1,6 +1,6 @@
 {
   "label": "🎓 Tutorials",
-  "position": 2,
+  "position": 3,
   "link": {
     "title": "Tutorials",
     "slug": "tutorials",
diff --git a/docs/uninstall.md b/docs/uninstall.md
index 3803dc16..a57ab7fe 100644
--- a/docs/uninstall.md
+++ b/docs/uninstall.md
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 6
+sidebar_position: 7
 title: 🛑 Uninstall
 description: How to disable Shorebird.
 ---

From 1d662eb87b62510a781af994388c696eb031ed59 Mon Sep 17 00:00:00 2001
From: Bryan Oltman <bryanoltman@gmail.com>
Date: Thu, 18 May 2023 09:56:20 -0400
Subject: [PATCH 07/26] rename app for clarity

---
 docs/tutorials/code_push_quickstart.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/tutorials/code_push_quickstart.md b/docs/tutorials/code_push_quickstart.md
index c73fc96f..c443307c 100644
--- a/docs/tutorials/code_push_quickstart.md
+++ b/docs/tutorials/code_push_quickstart.md
@@ -45,14 +45,14 @@ Once you have registered and subscribed, you're ready to use Shorebird!
 Start by creating a new Flutter app:
 
 ```sh
-flutter create shorebird_app
+flutter create my_shorebird_app
 ```
 
 As with any Flutter app, you can verify this created the standard Counter app by
 following the instructions printed by `flutter create`:
 
 ```sh
-cd shorebird_app
+cd my_shorebird_app
 flutter run
 ```
 

From a4f5f55da8da2b0cb3cfa5b961b407c8b595dead Mon Sep 17 00:00:00 2001
From: Bryan Oltman <bryanoltman@gmail.com>
Date: Thu, 18 May 2023 10:02:23 -0400
Subject: [PATCH 08/26] Fix link

---
 docs/tutorials/code_push_quickstart.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/tutorials/code_push_quickstart.md b/docs/tutorials/code_push_quickstart.md
index c443307c..0911d19e 100644
--- a/docs/tutorials/code_push_quickstart.md
+++ b/docs/tutorials/code_push_quickstart.md
@@ -8,7 +8,7 @@ description: Try code push for yourself
 
 This guide shows you the fastest way to install Shorebird and try code push.
 
-This document is a (slightly) condensed version of our [code push](../code_push/) docs, all on one page.
+This document is a (slightly) condensed version of our [code push](../code-push/) docs, all on one page.
 
 ## Sign up
 

From f02b1e368a43299fb7f2a5d93bc7625031d74b89 Mon Sep 17 00:00:00 2001
From: Bryan Oltman <bryanoltman@gmail.com>
Date: Thu, 18 May 2023 10:22:45 -0400
Subject: [PATCH 09/26] docs: add code push release guide

---
 docs/tutorials/code_push_release.md | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)
 create mode 100644 docs/tutorials/code_push_release.md

diff --git a/docs/tutorials/code_push_release.md b/docs/tutorials/code_push_release.md
new file mode 100644
index 00000000..58f7b4cf
--- /dev/null
+++ b/docs/tutorials/code_push_release.md
@@ -0,0 +1,21 @@
+---
+sidebar_position: 2
+title: 🚢 Release a code push app
+description: Release a code push app
+---
+
+# Releasing an code push app
+
+This guide walks you through releasing a code push app to the Play Store and applying a patch to that release.
+
+## Prerequisites
+
+This guide assumes that you have an existing Shorebird app. If you don't have one, you can create one by following the [code push quickstart](../code-push-quickstart/) guide.
+
+## Creating a release
+
+To create a release, run:
+
+```sh
+shorebird release
+```

From ca712b464d00eaf92305315cb3368c1ec2ccd31c Mon Sep 17 00:00:00 2001
From: Bryan Oltman <bryanoltman@gmail.com>
Date: Thu, 18 May 2023 11:11:17 -0400
Subject: [PATCH 10/26] update release docs through creating the release step

---
 docs/tutorials/code_push_release.md | 141 +++++++++++++++++++++++++++-
 1 file changed, 139 insertions(+), 2 deletions(-)

diff --git a/docs/tutorials/code_push_release.md b/docs/tutorials/code_push_release.md
index 58f7b4cf..f7689c94 100644
--- a/docs/tutorials/code_push_release.md
+++ b/docs/tutorials/code_push_release.md
@@ -12,10 +12,147 @@ This guide walks you through releasing a code push app to the Play Store and app
 
 This guide assumes that you have an existing Shorebird app. If you don't have one, you can create one by following the [code push quickstart](../code-push-quickstart/) guide.
 
+The app we will be releasing in this guide is [`Time Shift`](https://github.com/shorebirdtech/time_shift/), our demo code push app.
+
 ## Creating a release
 
-To create a release, run:
+### Determine next release version
+
+We will start by running `shorebird releases list` to see what releases have been created:
+
+```
+bryanoltman@boltman ~/Shorebird/time_shift (main)
+⑆ shorebird releases list
+🚀 Releases (51751336-6a7c-4972-b4ec-8fc1591fb2b3)
+┌─────────┬──────┐
+│ Version │ Name │
+├─────────┼──────┤
+│ 1.0.1   │ --   │
+├─────────┼──────┤
+│ 1.0.2+1 │ --   │
+├─────────┼──────┤
+│ 1.0.2+5 │ --   │
+└─────────┴──────┘
+```
+
+From this, we can see that the most recent release is `1.0.2+5`. This corresponds with what we see in the Play Store console:
+
+# TODO insert screenshot
+
+The release we are going to create is `1.0.3+6`.
+
+### Make code changes
+
+Version `1.0.3+6` of Time Shift will change the default clock face from `particle` to `generative`.
+
+To make this change, we will edit `lib/main.dart`:
+
+```diff
+   final clock = ClockFace.values.firstWhere(
+     (clock) => clock.name == clockName,
+-    orElse: () => ClockFace.particle,
++    orElse: () => ClockFace.generative,
+   );
+```
+
+We run the app using `shorebird run` to make sure this change does what we expect.
+
+After verifying, we will commit this change and push it to GitHub:
+
+```sh
+git add lib/main.dart
+git commit -m "Change default clock face to generative"
+git push
+```
+
+### Update app version
+
+We will now update the app version in `pubspec.yaml`:
+
+```diff
+name: time_shift
+description: Demo app showing Shorebird updates.
+publish_to: "none"
+
+-version: 1.0.2+5
++version: 1.0.3+6
+
+environment:
+  sdk: ">=2.19.4 <3.0.0"
+```
+
+We will commit this change, tag it, and push it.
 
 ```sh
-shorebird release
+git add pubspec.yaml
+git commit -m "Update app version to 1.0.3+6"
+git tag v1.0.3+6
+git push # Push the commit
+git push --tags  # Push the tags
+```
+
+### Create a Shorebird release
+
+To create a release, run `shorebird release`. You should see output similar to the following:
+
+```
+bryanoltman@boltman ~/Shorebird/time_shift (main)
+⑆ shorebird release
+✓ Building release (17.0s)
+✓ Fetching apps (0.3s)
+✓ Detecting release version (0.2s)
+
+🚀 Ready to create a new release!
+
+📱 App: time_shift (51751336-6a7c-4972-b4ec-8fc1591fb2b3)
+📦 Release Version: 1.0.3+6
+🕹️  Platform: android (arm64, arm32, x86_64)
+
+Would you like to continue? (y/N) Yes
+✓ Fetching releases (70ms)
+✓ Fetching Flutter revision (22ms)
+✓ Creating release (61ms)
+✓ Creating artifacts (2.5s)
+
+✅ Published Release!
+
+Your next step is to upload the app bundle to the Play Store.
+./build/app/outputs/bundle/release/app-release.aab
+
+See the following link for more information:
+https://support.google.com/googleplay/android-developer/answer/9859152?hl=en
 ```
+
+### Upload to the Play Store
+
+As per the instructions above, we need to upload the generated `.aab` to the Play Store.
+
+1. Navigate to the [Play Console](https://play.google.com/console/developers)
+1. Choose your developer account (for us, it's Shorebirdbird.dev)
+1. Select the Time Shift app.
+1. Select "Testing -> Open Testing" from the side bar.
+1. Click the "Create new release" button.
+
+You will now be prompted to upload the `.aab` file. You can find this file in `./build/app/outputs/bundle/release/app-release.aab`.
+
+1. From ~/Shorebird/time_shift, run `open ./build/app/outputs/bundle/release/` to open the folder containing the `.aab` in Finder.
+1. Drag `app-release.aab` into the Play Console to upload.
+
+The Play Store will recognize the new version as `6 (1.0.3)`.
+
+Click "Next" and then "Save" (both in the bottom-right corner) to submit.
+
+This will take you to the publishing overview page. Click "Submit for review" to submit the release for review.
+
+We now wait for the Play Store to approve this release.
+
+### Create a GitHub Release
+
+While we wait, we will create a GitHub release. For us, that looks like:
+
+1. Navigate to https://github.com/shorebirdtech/time_shift/releases.
+1. Click "Draft a new release".
+1. Choose the tag we created earlier (`v1.0.3+6`).
+1. Title the release "v1.0.3+6".
+1. Add a description of the release ("Changes the default clock face to 'generative'").
+1. Publish the release.

From 041d721c0ad3b2050220a9a16d1cce3dad954b22 Mon Sep 17 00:00:00 2001
From: Bryan Oltman <bryanoltman@gmail.com>
Date: Thu, 18 May 2023 11:25:01 -0400
Subject: [PATCH 11/26] Fix merge issues

---
 .../code_push_release.md                      |   0
 docs/tutorials/_category_.json                |  10 --
 docs/tutorials/code_push_quickstart.md        | 157 ------------------
 3 files changed, 167 deletions(-)
 rename docs/{tutorials => guides}/code_push_release.md (100%)
 delete mode 100644 docs/tutorials/_category_.json
 delete mode 100644 docs/tutorials/code_push_quickstart.md

diff --git a/docs/tutorials/code_push_release.md b/docs/guides/code_push_release.md
similarity index 100%
rename from docs/tutorials/code_push_release.md
rename to docs/guides/code_push_release.md
diff --git a/docs/tutorials/_category_.json b/docs/tutorials/_category_.json
deleted file mode 100644
index 5395c2c4..00000000
--- a/docs/tutorials/_category_.json
+++ /dev/null
@@ -1,10 +0,0 @@
-{
-  "label": "🎓 Tutorials",
-  "position": 3,
-  "link": {
-    "title": "Tutorials",
-    "slug": "tutorials",
-    "type": "generated-index",
-    "description": "A collection of guides that help you get the most out of Shorebird."
-  }
-}
diff --git a/docs/tutorials/code_push_quickstart.md b/docs/tutorials/code_push_quickstart.md
deleted file mode 100644
index 0911d19e..00000000
--- a/docs/tutorials/code_push_quickstart.md
+++ /dev/null
@@ -1,157 +0,0 @@
----
-sidebar_position: 1
-title: ☄️ Code Push Quickstart
-description: Try code push for yourself
----
-
-# Code Push Quickstart
-
-This guide shows you the fastest way to install Shorebird and try code push.
-
-This document is a (slightly) condensed version of our [code push](../code-push/) docs, all on one page.
-
-## Sign up
-
-Before you can create a Shorebird app, you will need to sign up for Shorebird.
-
-### Create an account
-
-To register as a Shorebird user, run:
-
-```sh
-shorebird account create
-```
-
-This will generate a Google sign in link. Follow the link and sign in with your
-Google account.
-
-### Subscribe
-
-Code push is currently only available to paid subscribers. To subscribe, run:
-
-```sh
-shorebird account subscribe
-```
-
-This will generate a payment Stripe payment link. Follow the link and enter your
-payment information.
-
-Subscriptions are $20/month. You can cancel at any time.
-
-## Create the app
-
-Once you have registered and subscribed, you're ready to use Shorebird!
-
-Start by creating a new Flutter app:
-
-```sh
-flutter create my_shorebird_app
-```
-
-As with any Flutter app, you can verify this created the standard Counter app by
-following the instructions printed by `flutter create`:
-
-```sh
-cd my_shorebird_app
-flutter run
-```
-
-### Initialize Shorebird
-
-To make this a Shorebird app, run:
-
-```sh
-shorebird init
-```
-
-This will create a `shorebird.yaml` file in the root of your project. This file
-contains your Shorebird `app_id`.
-
-Run `shorebird doctor` to ensure everything is set up correctly:
-
-```sh
-shorebird doctor
-```
-
-You will notice that this prints an error:
-
-```sh
-[✗] android/app/src/main/AndroidManifest.xml is missing the INTERNET permission.
-```
-
-This is because Shorebird requires the internet permission to download patches.
-You can fix this issue by running:
-
-```sh
-shorebird doctor --fix
-```
-
-### Run the app with Shorebird
-
-To run the app with Shorebird (that is, with [Shorebird's fork of the Flutter
-engine](/faq#how-does-shorebird-relate-to-flutter)), run:
-
-```sh
-shorebird run
-```
-
-Now kill the app on your device or emulator.
-
-### Create a release
-
-We will create a release using the unmodified Counter app. Run:
-
-```sh
-shorebird release
-```
-
-When prompted, use the suggested version number (`1.0.0+1`), and enter `y` when
-asked if you would like to continue.
-
-### Create a patch
-
-We will now make a small change to the Counter app. In `lib/main.dart`, change
-the app theme's `primarySwatch` from blue to green:
-
-```diff
-class MyApp extends StatelessWidget {
-  const MyApp({super.key});
-
-  // This widget is the root of your application.
-  @override
-  Widget build(BuildContext context) {
-    return MaterialApp(
-      title: 'Flutter Demo',
-      theme: ThemeData(
-        // This is the theme of your application.
-        //
-        // Try running your application with "flutter run". You'll see the
-        // application has a blue toolbar. Then, without quitting the app, try
-        // changing the primarySwatch below to Colors.green and then invoke
-        // "hot reload" (press "r" in the console where you ran "flutter run",
-        // or simply save your changes to "hot reload" in a Flutter IDE).
-        // Notice that the counter didn't reset back to zero; the application
-        // is not restarted.
--       primarySwatch: Colors.blue,
-+       primarySwatch: Colors.green,
-      ),
-      home: const MyHomePage(title: 'Flutter Demo Home Page'),
-    );
-  }
-}
-```
-
-After making this change, save the file and run:
-
-```sh
-shorebird patch
-```
-
-When prompted, use the suggested release version (`1.0.0+1`), and enter `y` when
-asked if you'd like to continue.
-
-### See the patch in action
-
-Launch the app from your device or emulator. The app will still have the
-original blue theme, but it will be downloading the patch we just created in the
-background. Kill and launch the app again, and the app will be green! 🎉

From 023c153f57093e507a9bb5606483a0f4fd9c3ef1 Mon Sep 17 00:00:00 2001
From: Bryan Oltman <bryanoltman@gmail.com>
Date: Thu, 18 May 2023 11:40:20 -0400
Subject: [PATCH 12/26] tweak

---
 docs/guides/code_push_release.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/guides/code_push_release.md b/docs/guides/code_push_release.md
index f7689c94..bb6d04a8 100644
--- a/docs/guides/code_push_release.md
+++ b/docs/guides/code_push_release.md
@@ -1,7 +1,7 @@
 ---
 sidebar_position: 2
-title: 🚢 Release a code push app
-description: Release a code push app
+title: 🚢 Release a Code Push app
+description: Release a Code Push app
 ---
 
 # Releasing an code push app
@@ -148,7 +148,7 @@ We now wait for the Play Store to approve this release.
 
 ### Create a GitHub Release
 
-While we wait, we will create a GitHub release. For us, that looks like:
+We also want to create a GitHub release. For us, that looks like:
 
 1. Navigate to https://github.com/shorebirdtech/time_shift/releases.
 1. Click "Draft a new release".

From 3ab41a32f1da24722e5ea26eadcaa91e0f0290f5 Mon Sep 17 00:00:00 2001
From: Bryan Oltman <bryanoltman@gmail.com>
Date: Thu, 18 May 2023 11:44:58 -0400
Subject: [PATCH 13/26] add screenshots

---
 docs/guides/code_push_release.md | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/docs/guides/code_push_release.md b/docs/guides/code_push_release.md
index bb6d04a8..da3bcca9 100644
--- a/docs/guides/code_push_release.md
+++ b/docs/guides/code_push_release.md
@@ -37,7 +37,7 @@ bryanoltman@boltman ~/Shorebird/time_shift (main)
 
 From this, we can see that the most recent release is `1.0.2+5`. This corresponds with what we see in the Play Store console:
 
-# TODO insert screenshot
+![ReleaseVersion](https://github.com/shorebirdtech/docs/assets/581764/e6b6c276-49de-4142-8f32-dbf5e41379fa)
 
 The release we are going to create is `1.0.3+6`.
 
@@ -133,6 +133,8 @@ As per the instructions above, we need to upload the generated `.aab` to the Pla
 1. Select "Testing -> Open Testing" from the side bar.
 1. Click the "Create new release" button.
 
+![CreateNewRelease](https://github.com/shorebirdtech/docs/assets/581764/90c9c7ed-bc39-4731-bfec-524f89e2baf6)
+
 You will now be prompted to upload the `.aab` file. You can find this file in `./build/app/outputs/bundle/release/app-release.aab`.
 
 1. From ~/Shorebird/time_shift, run `open ./build/app/outputs/bundle/release/` to open the folder containing the `.aab` in Finder.
@@ -140,11 +142,17 @@ You will now be prompted to upload the `.aab` file. You can find this file in `.
 
 The Play Store will recognize the new version as `6 (1.0.3)`.
 
+![UploadedBundle](https://github.com/shorebirdtech/docs/assets/581764/1994cb5a-4cd6-4f1b-a88c-f5aaa3d1433d)
+
 Click "Next" and then "Save" (both in the bottom-right corner) to submit.
 
 This will take you to the publishing overview page. Click "Submit for review" to submit the release for review.
 
-We now wait for the Play Store to approve this release.
+We should now see a release in the Play Store console with an "In review" status:
+
+![InReview](https://github.com/shorebirdtech/docs/assets/581764/4cfdc7fb-2049-4110-b1cd-da99c7a491f7)
+
+We will now wait for the Play Store to approve this release.
 
 ### Create a GitHub Release
 

From 1069d63912e218fb3542f7c398b18e787fb2ec7f Mon Sep 17 00:00:00 2001
From: Bryan Oltman <bryanoltman@gmail.com>
Date: Thu, 18 May 2023 11:49:20 -0400
Subject: [PATCH 14/26] add play store link

---
 docs/guides/code_push_release.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/guides/code_push_release.md b/docs/guides/code_push_release.md
index da3bcca9..4f82241b 100644
--- a/docs/guides/code_push_release.md
+++ b/docs/guides/code_push_release.md
@@ -12,7 +12,7 @@ This guide walks you through releasing a code push app to the Play Store and app
 
 This guide assumes that you have an existing Shorebird app. If you don't have one, you can create one by following the [code push quickstart](../code-push-quickstart/) guide.
 
-The app we will be releasing in this guide is [`Time Shift`](https://github.com/shorebirdtech/time_shift/), our demo code push app.
+The app we will be releasing in this guide is [`Time Shift`](https://play.google.com/store/apps/details?id=dev.shorebird.u_shorebird_clock), our demo code push app. ([source](https://github.com/shorebirdtech/time_shift/))
 
 ## Creating a release
 

From ae9343b9cc13fd5292af628c8c2d5d71f37054c2 Mon Sep 17 00:00:00 2001
From: Bryan Oltman <bryanoltman@gmail.com>
Date: Thu, 18 May 2023 11:56:24 -0400
Subject: [PATCH 15/26] minor updates

---
 docs/guides/code_push_release.md | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/docs/guides/code_push_release.md b/docs/guides/code_push_release.md
index 4f82241b..29b02280 100644
--- a/docs/guides/code_push_release.md
+++ b/docs/guides/code_push_release.md
@@ -18,7 +18,7 @@ The app we will be releasing in this guide is [`Time Shift`](https://play.google
 
 ### Determine next release version
 
-We will start by running `shorebird releases list` to see what releases have been created:
+We will start by running `shorebird releases list` to see the current set of releases:
 
 ```
 bryanoltman@boltman ~/Shorebird/time_shift (main)
@@ -43,7 +43,7 @@ The release we are going to create is `1.0.3+6`.
 
 ### Make code changes
 
-Version `1.0.3+6` of Time Shift will change the default clock face from `particle` to `generative`.
+Version `1.0.3+6` of Time Shift will be a small patch that changes the default clock face from `particle` to `generative`.
 
 To make this change, we will edit `lib/main.dart`:
 
@@ -88,12 +88,12 @@ git add pubspec.yaml
 git commit -m "Update app version to 1.0.3+6"
 git tag v1.0.3+6
 git push # Push the commit
-git push --tags  # Push the tags
+git push --tags  # Push the tag
 ```
 
 ### Create a Shorebird release
 
-To create a release, run `shorebird release`. You should see output similar to the following:
+To create a Shorebird release, run `shorebird release`. You should see output similar to the following:
 
 ```
 bryanoltman@boltman ~/Shorebird/time_shift (main)
@@ -106,7 +106,7 @@ bryanoltman@boltman ~/Shorebird/time_shift (main)
 
 📱 App: time_shift (51751336-6a7c-4972-b4ec-8fc1591fb2b3)
 📦 Release Version: 1.0.3+6
-🕹️  Platform: android (arm64, arm32, x86_64)
+🕹️ Platform: android (arm64, arm32, x86_64)
 
 Would you like to continue? (y/N) Yes
 ✓ Fetching releases (70ms)
@@ -127,8 +127,8 @@ https://support.google.com/googleplay/android-developer/answer/9859152?hl=en
 
 As per the instructions above, we need to upload the generated `.aab` to the Play Store.
 
-1. Navigate to the [Play Console](https://play.google.com/console/developers)
-1. Choose your developer account (for us, it's Shorebirdbird.dev)
+1. Navigate to the [Play Console](https://play.google.com/console/developers).
+1. Choose your developer account (for us, it's Shorebirdbird.dev).
 1. Select the Time Shift app.
 1. Select "Testing -> Open Testing" from the side bar.
 1. Click the "Create new release" button.
@@ -137,10 +137,10 @@ As per the instructions above, we need to upload the generated `.aab` to the Pla
 
 You will now be prompted to upload the `.aab` file. You can find this file in `./build/app/outputs/bundle/release/app-release.aab`.
 
-1. From ~/Shorebird/time_shift, run `open ./build/app/outputs/bundle/release/` to open the folder containing the `.aab` in Finder.
+1. From `~/Shorebird/time_shift`, run `open ./build/app/outputs/bundle/release/` to open the folder containing the `.aab` in Finder.
 1. Drag `app-release.aab` into the Play Console to upload.
 
-The Play Store will recognize the new version as `6 (1.0.3)`.
+Once the uplaod completes, the Play Store will correctly recognize the new version as `6 (1.0.3)`.
 
 ![UploadedBundle](https://github.com/shorebirdtech/docs/assets/581764/1994cb5a-4cd6-4f1b-a88c-f5aaa3d1433d)
 

From 57c74f0afb1601cdc581776d1acf250d9f1220d6 Mon Sep 17 00:00:00 2001
From: Bryan Oltman <bryanoltman@gmail.com>
Date: Thu, 18 May 2023 12:03:07 -0400
Subject: [PATCH 16/26] Formatting, add GH links

---
 docs/guides/code_push_release.md | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/docs/guides/code_push_release.md b/docs/guides/code_push_release.md
index 29b02280..8661d66a 100644
--- a/docs/guides/code_push_release.md
+++ b/docs/guides/code_push_release.md
@@ -1,7 +1,7 @@
 ---
 sidebar_position: 2
-title: 🚢 Release a Code Push app
-description: Release a Code Push app
+title: 🚢 Release a Code Push App
+description: Release a Code Push App
 ---
 
 # Releasing an code push app
@@ -14,7 +14,7 @@ This guide assumes that you have an existing Shorebird app. If you don't have on
 
 The app we will be releasing in this guide is [`Time Shift`](https://play.google.com/store/apps/details?id=dev.shorebird.u_shorebird_clock), our demo code push app. ([source](https://github.com/shorebirdtech/time_shift/))
 
-## Creating a release
+## Creating a Release
 
 ### Determine next release version
 
@@ -65,6 +65,8 @@ git commit -m "Change default clock face to generative"
 git push
 ```
 
+[On GitHub](https://github.com/shorebirdtech/time_shift/commit/d1fe9451aa18a775163bce95dd9dab551aaf6259)
+
 ### Update app version
 
 We will now update the app version in `pubspec.yaml`:
@@ -91,6 +93,8 @@ git push # Push the commit
 git push --tags  # Push the tag
 ```
 
+[On GitHub](https://github.com/shorebirdtech/time_shift/commit/3b25df1888c170c2418162ba64a9a5e6363c09af)
+
 ### Create a Shorebird release
 
 To create a Shorebird release, run `shorebird release`. You should see output similar to the following:

From 8458f21e619a440b1378f24d252808813c7fe823 Mon Sep 17 00:00:00 2001
From: Bryan Oltman <bryanoltman@gmail.com>
Date: Thu, 18 May 2023 12:18:27 -0400
Subject: [PATCH 17/26] Add patch instructions

---
 docs/guides/code_push_release.md | 82 ++++++++++++++++++++++++++++++++
 1 file changed, 82 insertions(+)

diff --git a/docs/guides/code_push_release.md b/docs/guides/code_push_release.md
index 8661d66a..c0b3800e 100644
--- a/docs/guides/code_push_release.md
+++ b/docs/guides/code_push_release.md
@@ -168,3 +168,85 @@ We also want to create a GitHub release. For us, that looks like:
 1. Title the release "v1.0.3+6".
 1. Add a description of the release ("Changes the default clock face to 'generative'").
 1. Publish the release.
+
+## After the Release is Approved
+
+Once the release has been approved, you will be able to download it from the Play Store.
+
+## Creating a Patch
+
+Let's say we want to create a patch for `1.0.3+6` that fixes a bug.
+
+### Make the change
+
+We start by checking out the `v1.0.3+6` release tag:
+
+```sh
+git checkout v1.0.3+6
+```
+
+We will branch from here, as this change will represent a divergence from the `main` branch:
+
+```sh
+git checkout -b v1.0.3+6-patch1
+```
+
+For the purposes of this guide, we will change the default clock face back to `particle` in `lib/main.dart`:
+
+```diff
+     (clock) => clock.name == clockName,
+-    orElse: () => ClockFace.generative,
++    orElse: () => ClockFace.particle,
+   );
+```
+
+Commit this change and push the branch:
+
+```sh
+git add lib/main.dart
+git commit -m "Change default clock face to particle"
+git push --set-upstream origin v1.0.3+6-patch1
+```
+
+We will also tag this commit as `v1.0.3+6-patch1`:
+
+```sh
+git tag v1.0.3+6-patch1
+git push --tags
+```
+
+[On GitHub](https://github.com/shorebirdtech/time_shift/commit/cf4054bada74ff1c5ff84fb9aceb3f1e4442203f)
+
+### Create a Shorebird Patch
+
+We will now create a patch with `shorebird patch`. You should see output similar to the following:
+
+```
+bryanoltman@boltman ~/Shorebird/time_shift (main)
+⑆ shorebird patch
+✓ Building patch (17.2s)
+✓ Fetching apps (0.7s)
+✓ Detecting release version (0.2s)
+✓ Fetching release (99ms)
+✓ Fetching Flutter revision (13ms)
+✓ Fetching release artifacts (0.2s)
+✓ Downloading release artifacts (1.0s)
+✓ Creating artifacts (1.0s)
+
+🚀 Ready to publish a new patch!
+
+📱 App: time_shift (51751336-6a7c-4972-b4ec-8fc1591fb2b3)
+📦 Release Version: 1.0.3+6
+📺 Channel: stable
+🕹️  Platform: android [arm64 (135 B), arm32 (150 B), x86_64 (135 B)]
+
+Would you like to continue? (y/N) Yes
+✓ Creating patch (0.1s)
+✓ Uploading artifacts (0.9s)
+✓ Fetching channels (90ms)
+✓ Promoting patch to stable (61ms)
+
+✅ Published Patch!
+```
+
+This change will now be available to users with version `1.0.3+6` of the app.

From e330cd164fb54aa5af9de153f2ea4f944cbc7cba Mon Sep 17 00:00:00 2001
From: Bryan Oltman <bryanoltman@gmail.com>
Date: Thu, 18 May 2023 12:20:56 -0400
Subject: [PATCH 18/26] fix link

---
 docs/guides/code_push_release.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/guides/code_push_release.md b/docs/guides/code_push_release.md
index c0b3800e..9b5f22d7 100644
--- a/docs/guides/code_push_release.md
+++ b/docs/guides/code_push_release.md
@@ -10,7 +10,7 @@ This guide walks you through releasing a code push app to the Play Store and app
 
 ## Prerequisites
 
-This guide assumes that you have an existing Shorebird app. If you don't have one, you can create one by following the [code push quickstart](../code-push-quickstart/) guide.
+This guide assumes that you have an existing Shorebird app. If you don't have one, you can create one by following the [code push quickstart](./code_push_quickstart/) guide.
 
 The app we will be releasing in this guide is [`Time Shift`](https://play.google.com/store/apps/details?id=dev.shorebird.u_shorebird_clock), our demo code push app. ([source](https://github.com/shorebirdtech/time_shift/))
 

From 1e18b2da925957f4bcdb36f842f1c4b54813a69b Mon Sep 17 00:00:00 2001
From: Bryan Oltman <bryanoltman@gmail.com>
Date: Thu, 18 May 2023 12:36:27 -0400
Subject: [PATCH 19/26] Fix typo

Co-authored-by: Felix Angelov <felix@shorebird.dev>
---
 docs/guides/code_push_release.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/guides/code_push_release.md b/docs/guides/code_push_release.md
index 9b5f22d7..a1a00fab 100644
--- a/docs/guides/code_push_release.md
+++ b/docs/guides/code_push_release.md
@@ -4,7 +4,7 @@ title: 🚢 Release a Code Push App
 description: Release a Code Push App
 ---
 
-# Releasing an code push app
+# Releasing a code push app
 
 This guide walks you through releasing a code push app to the Play Store and applying a patch to that release.
 

From f7a48ac55d4ac8fba595a492c4bf9252d23b7c77 Mon Sep 17 00:00:00 2001
From: Bryan Oltman <bryanoltman@gmail.com>
Date: Thu, 18 May 2023 12:37:02 -0400
Subject: [PATCH 20/26] Copy edit

Co-authored-by: Felix Angelov <felix@shorebird.dev>
---
 docs/guides/code_push_release.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/guides/code_push_release.md b/docs/guides/code_push_release.md
index a1a00fab..92c7b0f7 100644
--- a/docs/guides/code_push_release.md
+++ b/docs/guides/code_push_release.md
@@ -35,7 +35,7 @@ bryanoltman@boltman ~/Shorebird/time_shift (main)
 └─────────┴──────┘
 ```
 
-From this, we can see that the most recent release is `1.0.2+5`. This corresponds with what we see in the Play Store console:
+We can see that the most recent release is `1.0.2+5`. This corresponds with what we see in the Play Store console:
 
 ![ReleaseVersion](https://github.com/shorebirdtech/docs/assets/581764/e6b6c276-49de-4142-8f32-dbf5e41379fa)
 

From e2f98fbe01550ce88715338a186df8b4884a1c7a Mon Sep 17 00:00:00 2001
From: Bryan Oltman <bryanoltman@gmail.com>
Date: Thu, 18 May 2023 12:40:28 -0400
Subject: [PATCH 21/26] Remove "you"

Co-authored-by: Felix Angelov <felix@shorebird.dev>
---
 docs/guides/code_push_release.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/guides/code_push_release.md b/docs/guides/code_push_release.md
index 92c7b0f7..390a96f8 100644
--- a/docs/guides/code_push_release.md
+++ b/docs/guides/code_push_release.md
@@ -6,7 +6,7 @@ description: Release a Code Push App
 
 # Releasing a code push app
 
-This guide walks you through releasing a code push app to the Play Store and applying a patch to that release.
+This guide walks through releasing a code push app to the Play Store and applying a patch to that release.
 
 ## Prerequisites
 

From d4e0df26b66fa5dead9b5d9a4d3b94bccae5ea6e Mon Sep 17 00:00:00 2001
From: Bryan Oltman <bryanoltman@gmail.com>
Date: Thu, 18 May 2023 12:41:10 -0400
Subject: [PATCH 22/26] standardize header casing

---
 docs/guides/code_push_release.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/docs/guides/code_push_release.md b/docs/guides/code_push_release.md
index 390a96f8..55269db0 100644
--- a/docs/guides/code_push_release.md
+++ b/docs/guides/code_push_release.md
@@ -14,7 +14,7 @@ This guide assumes that you have an existing Shorebird app. If you don't have on
 
 The app we will be releasing in this guide is [`Time Shift`](https://play.google.com/store/apps/details?id=dev.shorebird.u_shorebird_clock), our demo code push app. ([source](https://github.com/shorebirdtech/time_shift/))
 
-## Creating a Release
+## Creating a release
 
 ### Determine next release version
 
@@ -158,7 +158,7 @@ We should now see a release in the Play Store console with an "In review" status
 
 We will now wait for the Play Store to approve this release.
 
-### Create a GitHub Release
+### Create a GitHub release
 
 We also want to create a GitHub release. For us, that looks like:
 
@@ -169,11 +169,11 @@ We also want to create a GitHub release. For us, that looks like:
 1. Add a description of the release ("Changes the default clock face to 'generative'").
 1. Publish the release.
 
-## After the Release is Approved
+## After the release is approved
 
 Once the release has been approved, you will be able to download it from the Play Store.
 
-## Creating a Patch
+## Creating a patch
 
 Let's say we want to create a patch for `1.0.3+6` that fixes a bug.
 
@@ -217,7 +217,7 @@ git push --tags
 
 [On GitHub](https://github.com/shorebirdtech/time_shift/commit/cf4054bada74ff1c5ff84fb9aceb3f1e4442203f)
 
-### Create a Shorebird Patch
+### Create a Shorebird patch
 
 We will now create a patch with `shorebird patch`. You should see output similar to the following:
 

From 5c6f110ea7d3c8f38590f7badb1d56e447e37f08 Mon Sep 17 00:00:00 2001
From: Bryan Oltman <bryanoltman@gmail.com>
Date: Thu, 18 May 2023 12:42:18 -0400
Subject: [PATCH 23/26] Add clarity to shorebird releases list command

Co-authored-by: Felix Angelov <felix@shorebird.dev>
---
 docs/guides/code_push_release.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/guides/code_push_release.md b/docs/guides/code_push_release.md
index 55269db0..572e3075 100644
--- a/docs/guides/code_push_release.md
+++ b/docs/guides/code_push_release.md
@@ -18,7 +18,7 @@ The app we will be releasing in this guide is [`Time Shift`](https://play.google
 
 ### Determine next release version
 
-We will start by running `shorebird releases list` to see the current set of releases:
+We will start by running `shorebird releases list` from the root directory of our project to see the current set of releases:
 
 ```
 bryanoltman@boltman ~/Shorebird/time_shift (main)

From 29c63578b257b8089a85daa540a82ebca0126d05 Mon Sep 17 00:00:00 2001
From: Bryan Oltman <bryanoltman@gmail.com>
Date: Thu, 18 May 2023 12:52:07 -0400
Subject: [PATCH 24/26] bulk copy edits

---
 docs/guides/code_push_release.md | 46 ++++++++++++++++----------------
 1 file changed, 23 insertions(+), 23 deletions(-)

diff --git a/docs/guides/code_push_release.md b/docs/guides/code_push_release.md
index 55269db0..eaa98b77 100644
--- a/docs/guides/code_push_release.md
+++ b/docs/guides/code_push_release.md
@@ -18,7 +18,7 @@ The app we will be releasing in this guide is [`Time Shift`](https://play.google
 
 ### Determine next release version
 
-We will start by running `shorebird releases list` to see the current set of releases:
+Start by running `shorebird releases list` to see the current set of releases:
 
 ```
 bryanoltman@boltman ~/Shorebird/time_shift (main)
@@ -35,17 +35,17 @@ bryanoltman@boltman ~/Shorebird/time_shift (main)
 └─────────┴──────┘
 ```
 
-We can see that the most recent release is `1.0.2+5`. This corresponds with what we see in the Play Store console:
+This shows that the most recent release is `1.0.2+5`. This corresponds with what we see in the Play Store console:
 
 ![ReleaseVersion](https://github.com/shorebirdtech/docs/assets/581764/e6b6c276-49de-4142-8f32-dbf5e41379fa)
 
-The release we are going to create is `1.0.3+6`.
+Next, we'll create a new release for version `1.0.3+6`.
 
 ### Make code changes
 
-Version `1.0.3+6` of Time Shift will be a small patch that changes the default clock face from `particle` to `generative`.
+Version `1.0.3+6` of Time Shift will change the default clock face from `particle` to `generative`.
 
-To make this change, we will edit `lib/main.dart`:
+To make this change, edit `lib/main.dart`:
 
 ```diff
    final clock = ClockFace.values.firstWhere(
@@ -55,9 +55,9 @@ To make this change, we will edit `lib/main.dart`:
    );
 ```
 
-We run the app using `shorebird run` to make sure this change does what we expect.
+Verify that this change does what we expect by running the app with `shorebird run`.
 
-After verifying, we will commit this change and push it to GitHub:
+Once this change has been verified, commit this change and push it to GitHub:
 
 ```sh
 git add lib/main.dart
@@ -69,7 +69,7 @@ git push
 
 ### Update app version
 
-We will now update the app version in `pubspec.yaml`:
+Next, bump the app version in `pubspec.yaml`:
 
 ```diff
 name: time_shift
@@ -83,7 +83,7 @@ environment:
   sdk: ">=2.19.4 <3.0.0"
 ```
 
-We will commit this change, tag it, and push it.
+Commit, tag, and push the change.
 
 ```sh
 git add pubspec.yaml
@@ -129,7 +129,7 @@ https://support.google.com/googleplay/android-developer/answer/9859152?hl=en
 
 ### Upload to the Play Store
 
-As per the instructions above, we need to upload the generated `.aab` to the Play Store.
+As per the instructions above, we must upload the generated `.aab` to the Play Store.
 
 1. Navigate to the [Play Console](https://play.google.com/console/developers).
 1. Choose your developer account (for us, it's Shorebirdbird.dev).
@@ -139,12 +139,12 @@ As per the instructions above, we need to upload the generated `.aab` to the Pla
 
 ![CreateNewRelease](https://github.com/shorebirdtech/docs/assets/581764/90c9c7ed-bc39-4731-bfec-524f89e2baf6)
 
-You will now be prompted to upload the `.aab` file. You can find this file in `./build/app/outputs/bundle/release/app-release.aab`.
+Upload the `.aab` file located at `./build/app/outputs/bundle/release/app-release.aab`.
 
-1. From `~/Shorebird/time_shift`, run `open ./build/app/outputs/bundle/release/` to open the folder containing the `.aab` in Finder.
+1. From the root directory of the project, run `open ./build/app/outputs/bundle/release/` to open the folder containing the `.aab` in Finder.
 1. Drag `app-release.aab` into the Play Console to upload.
 
-Once the uplaod completes, the Play Store will correctly recognize the new version as `6 (1.0.3)`.
+Once the upload completes, the Play Store will correctly recognize the new version as `6 (1.0.3)`.
 
 ![UploadedBundle](https://github.com/shorebirdtech/docs/assets/581764/1994cb5a-4cd6-4f1b-a88c-f5aaa3d1433d)
 
@@ -152,15 +152,15 @@ Click "Next" and then "Save" (both in the bottom-right corner) to submit.
 
 This will take you to the publishing overview page. Click "Submit for review" to submit the release for review.
 
-We should now see a release in the Play Store console with an "In review" status:
+You should now see a release in the Play Store console with an "In review" status:
 
 ![InReview](https://github.com/shorebirdtech/docs/assets/581764/4cfdc7fb-2049-4110-b1cd-da99c7a491f7)
 
-We will now wait for the Play Store to approve this release.
+Now you must wait for the Play Store to approve the release.
 
 ### Create a GitHub release
 
-We also want to create a GitHub release. For us, that looks like:
+It's recommended to create a GitHub release as well.
 
 1. Navigate to https://github.com/shorebirdtech/time_shift/releases.
 1. Click "Draft a new release".
@@ -175,17 +175,17 @@ Once the release has been approved, you will be able to download it from the Pla
 
 ## Creating a patch
 
-Let's say we want to create a patch for `1.0.3+6` that fixes a bug.
+Patches can be pushed to fix bugs in the `1.0.3+6` release without requiring a new submission to the Play Store.
 
 ### Make the change
 
-We start by checking out the `v1.0.3+6` release tag:
+Start by checking out the `v1.0.3+6` release tag:
 
 ```sh
 git checkout v1.0.3+6
 ```
 
-We will branch from here, as this change will represent a divergence from the `main` branch:
+Next, create a branch, as this change will represent a divergence from the `main` branch:
 
 ```sh
 git checkout -b v1.0.3+6-patch1
@@ -200,7 +200,7 @@ For the purposes of this guide, we will change the default clock face back to `p
    );
 ```
 
-Commit this change and push the branch:
+Commit the change and push our new patch branch:
 
 ```sh
 git add lib/main.dart
@@ -208,7 +208,7 @@ git commit -m "Change default clock face to particle"
 git push --set-upstream origin v1.0.3+6-patch1
 ```
 
-We will also tag this commit as `v1.0.3+6-patch1`:
+Tag this commit as `v1.0.3+6-patch1`:
 
 ```sh
 git tag v1.0.3+6-patch1
@@ -219,7 +219,7 @@ git push --tags
 
 ### Create a Shorebird patch
 
-We will now create a patch with `shorebird patch`. You should see output similar to the following:
+Finally, push the patch with `shorebird patch`. You should see output similar to the following:
 
 ```
 bryanoltman@boltman ~/Shorebird/time_shift (main)
@@ -249,4 +249,4 @@ Would you like to continue? (y/N) Yes
 ✅ Published Patch!
 ```
 
-This change will now be available to users with version `1.0.3+6` of the app.
+This patch will now be available to users with version `1.0.3+6` of the app.

From 56d58374e296cb1ee34e29135ba3d45d653d0ea6 Mon Sep 17 00:00:00 2001
From: Bryan Oltman <bryanoltman@gmail.com>
Date: Thu, 18 May 2023 13:15:49 -0400
Subject: [PATCH 25/26] Add delete branch instructions

---
 docs/guides/code_push_release.md | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/docs/guides/code_push_release.md b/docs/guides/code_push_release.md
index eaa98b77..7277889d 100644
--- a/docs/guides/code_push_release.md
+++ b/docs/guides/code_push_release.md
@@ -250,3 +250,13 @@ Would you like to continue? (y/N) Yes
 ```
 
 This patch will now be available to users with version `1.0.3+6` of the app.
+
+### Cleanup
+
+Delete the branch to keep the repository tidy:
+
+```sh
+git checkout main
+git branch -D v1.0.3+6-patch1
+git push origin --delete v1.0.3+6-patch1
+```

From 08e1358665827199ad733be6f73f65f54ab6b7dc Mon Sep 17 00:00:00 2001
From: Bryan Oltman <bryanoltman@gmail.com>
Date: Thu, 18 May 2023 13:19:00 -0400
Subject: [PATCH 26/26] Add note about the commit still existing

---
 docs/guides/code_push_release.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/guides/code_push_release.md b/docs/guides/code_push_release.md
index 7277889d..48aa2b35 100644
--- a/docs/guides/code_push_release.md
+++ b/docs/guides/code_push_release.md
@@ -260,3 +260,5 @@ git checkout main
 git branch -D v1.0.3+6-patch1
 git push origin --delete v1.0.3+6-patch1
 ```
+
+> Note: this change is still accessible via the `v1.0.3+6-patch1` tag.