From c32280814d65928a7dab9e4c7ccca25aaa4a7cdb Mon Sep 17 00:00:00 2001
From: Eric Seidel <eric@shorebird.dev>
Date: Fri, 19 Jul 2024 11:06:08 -0700
Subject: [PATCH] docs: expand the "when should I patch" answer.
---
src/content/docs/faq.mdx | 34 +++++++++++++++++++++++++++++++---
1 file changed, 31 insertions(+), 3 deletions(-)
diff --git a/src/content/docs/faq.mdx b/src/content/docs/faq.mdx
index 2d8fee7d..7448abc8 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,37 @@ 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?
+
+Since 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 version". The "release version" is a store
+concept, where as "patch version" 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 here. I'll enumerate a few
+here:
+
+1. Some customers push a patch immediately updating 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. Some customers 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. Finally some customers continue to only use releases for shipping code
+ changes, and reserve patching for emergencies only.
-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. Anecdotally I expect
+option 2 is the most common we see with current customers.
-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