From 1c386e51bf5b6187c2d174622dc9768b1556b14f Mon Sep 17 00:00:00 2001 From: Bryan Oltman Date: Thu, 18 May 2023 11:16:10 -0400 Subject: [PATCH] docs: adds code push quickstart guide (#28) * docs: minor copy edits to initialize.md * docs: adds code push quickstart guide * format * Move quickstart to tutorials section * format * update positions * rename app for clarity * Fix link * rename 'tutorials' to 'guides' --- docs/architecture.md | 2 +- docs/faq.md | 2 +- docs/guides/_category_.json | 10 ++ docs/guides/code_push_quickstart.md | 157 ++++++++++++++++++++++++++++ docs/status.md | 2 +- docs/uninstall.md | 2 +- 6 files changed, 171 insertions(+), 4 deletions(-) create mode 100644 docs/guides/_category_.json create mode 100644 docs/guides/code_push_quickstart.md 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/guides/_category_.json b/docs/guides/_category_.json new file mode 100644 index 00000000..1b5919aa --- /dev/null +++ b/docs/guides/_category_.json @@ -0,0 +1,10 @@ +{ + "label": "πŸ—ΊοΈ Guides", + "position": 3, + "link": { + "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/guides/code_push_quickstart.md b/docs/guides/code_push_quickstart.md new file mode 100644 index 00000000..0911d19e --- /dev/null +++ b/docs/guides/code_push_quickstart.md @@ -0,0 +1,157 @@ +--- +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! πŸŽ‰ 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/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. ---