From f610fa14a96270f785086b6b2fb7f38a06117716 Mon Sep 17 00:00:00 2001 From: Eric Seidel Date: Mon, 22 Jul 2024 09:22:53 -0700 Subject: [PATCH] docs: expand the "when should I patch" answer. (#273) * docs: expand the "when should I patch" answer. * Update src/content/docs/faq.mdx Co-authored-by: Bryan Oltman * Update src/content/docs/faq.mdx Co-authored-by: Bryan Oltman * Update src/content/docs/faq.mdx Co-authored-by: Bryan Oltman * Update src/content/docs/faq.mdx Co-authored-by: Bryan Oltman * Update src/content/docs/faq.mdx Co-authored-by: Bryan Oltman * Update src/content/docs/faq.mdx Co-authored-by: Bryan Oltman * Update src/content/docs/faq.mdx Co-authored-by: Bryan Oltman * fix faq link * Update src/content/docs/faq.mdx Co-authored-by: Bryan Oltman --------- Co-authored-by: Bryan Oltman --- src/content/docs/concepts.mdx | 4 +++- src/content/docs/faq.mdx | 35 ++++++++++++++++++++++++++++++++--- 2 files changed, 35 insertions(+), 4 deletions(-) diff --git a/src/content/docs/concepts.mdx b/src/content/docs/concepts.mdx index ac919a9e..0362e825 100644 --- a/src/content/docs/concepts.mdx +++ b/src/content/docs/concepts.mdx @@ -3,6 +3,8 @@ title: Code Push Concepts description: Concepts used in Shorebird's code push product. --- +{/* cspell:words pubspec libapp */} + An explanation of the concepts used in Shorebird's code push product. ## Code Push @@ -71,7 +73,7 @@ When your application starts, it checks for available patches and applies the la Patches are created by running `shorebird patch [platform]`, where `platform` is `android`, `aar`, or `ios`. :::note -For more information regarding when to create a patch, refer to our [FAQs](/faq#when-should-i-create-a-patch) +For more information regarding when to create a patch, refer to our [FAQs](/faq#when-should-i-create-a-patch-vs-a-release) ::: ### Artifact diff --git a/src/content/docs/faq.mdx b/src/content/docs/faq.mdx index 2d8fee7d..142931c2 100644 --- a/src/content/docs/faq.mdx +++ b/src/content/docs/faq.mdx @@ -3,6 +3,8 @@ title: FAQ description: Frequently asked questions. --- +{/* cspell:words appcenter codepush aarch rollouts */} + If you have questions not answered here, please ask! Both filing an issue or asking on [Discord](https://discord.gg/shorebird) work. @@ -449,11 +451,38 @@ If you'd like to segment availability of Shorebird patches, there are 4 potentia Yes. Apps built with Shorebird will continue to function normally (as if they had been built without Shorebird), including those that have had patches installed. -### When should I create a patch? +### When should I create a patch vs a release? + +Because patching and releasing are independent operations, it is possible to +create both a patch and a release with the same code changes. + +:::note +A "release" gets a unique release version, while a "patch" does not change +the release version, just the "patch number". The "release version" is a store +concept, where as "patch number" is a Shorebird concept. Apps can read the +current patch version at runtime via the +[package:shorebird_code_push](https://pub.dev/packages/shorebird_code_push). +::: + +Different customers have used different policies to decide whether to create a release, a patch, or both. I'll enumerate a few of these here: + +1. Push a patch immediately to update all existing users, while + also simultaneously submitting a release to the stores so that new users to + their product will get the latest code on first launch after a store + install. + +2. Use patching as a mechanism to ship changes on a high + frequency (e.g. daily or weekly) and only go through a full release process + on a lower cadence (e.g. monthly). + +3. Continue to only use releases for shipping code changes, and only patch to fix critical bugs or make other emergency changes. -Generally, you should create patches when fixing bugs that **DO NOT** contain native changes or asset changes. For all other changes, you should likely create a new release. +In the end, it comes down to what works for your business. We see most of our current customers choosing option 2. -If distributing through stores, please refer to store policies for additional guidelines. +:::note +Changes which involve native code cannot be patched and thus must use a +release for distribution. +::: ## Billing