From 6dd13013977b74669f6eac66d3fde93a367a7b24 Mon Sep 17 00:00:00 2001 From: Bryan Oltman Date: Thu, 4 May 2023 13:42:59 -0400 Subject: [PATCH 1/9] 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 Date: Thu, 4 May 2023 17:42:29 -0400 Subject: [PATCH 2/9] 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 Date: Wed, 17 May 2023 22:23:59 -0400 Subject: [PATCH 3/9] 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 Date: Wed, 17 May 2023 22:52:58 -0400 Subject: [PATCH 4/9] 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 Date: Thu, 18 May 2023 09:53:22 -0400 Subject: [PATCH 5/9] 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 Date: Thu, 18 May 2023 09:54:38 -0400 Subject: [PATCH 6/9] 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 Date: Thu, 18 May 2023 09:56:20 -0400 Subject: [PATCH 7/9] 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 Date: Thu, 18 May 2023 10:02:23 -0400 Subject: [PATCH 8/9] 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 07591a229a907154e54d362f9832c0b50bc7f3ff Mon Sep 17 00:00:00 2001 From: Bryan Oltman Date: Thu, 18 May 2023 11:14:02 -0400 Subject: [PATCH 9/9] rename 'tutorials' to 'guides' --- docs/{tutorials => guides}/_category_.json | 6 +++--- docs/{tutorials => guides}/code_push_quickstart.md | 0 2 files changed, 3 insertions(+), 3 deletions(-) rename docs/{tutorials => guides}/_category_.json (66%) rename docs/{tutorials => guides}/code_push_quickstart.md (100%) diff --git a/docs/tutorials/_category_.json b/docs/guides/_category_.json similarity index 66% rename from docs/tutorials/_category_.json rename to docs/guides/_category_.json index 5395c2c4..1b5919aa 100644 --- a/docs/tutorials/_category_.json +++ b/docs/guides/_category_.json @@ -1,9 +1,9 @@ { - "label": "πŸŽ“ Tutorials", + "label": "πŸ—ΊοΈ Guides", "position": 3, "link": { - "title": "Tutorials", - "slug": "tutorials", + "title": "Guides", + "slug": "guides", "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/guides/code_push_quickstart.md similarity index 100% rename from docs/tutorials/code_push_quickstart.md rename to docs/guides/code_push_quickstart.md