Skip to content

Commit 72d4340

Browse files
riderxriderx
committed
chore: add doc for breaking change
1 parent 5473046 commit 72d4340

File tree

2 files changed

+169
-33
lines changed

2 files changed

+169
-33
lines changed

‎src/content/docs/docs/cli/migrations/encryption.md‎

Lines changed: 42 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -5,73 +5,82 @@ sidebar:
55
order: 5
66
---
77

8-
This documentation will explain how to encrypt your data with the new encryption system and remove the old one.
8+
This documentation explains how to migrate to the new encryption system. Learn more about the new encryption system in the [blog post](/blog/introducing-end-to-end-security-to-capacitor-updater-with-code-signing).
99

10-
Learn more about the new encryption system in the [blog post](/blog/introducing-end-to-end-security-to-capacitor-updater-with-code-signing).
11-
12-
---
13-
14-
First, create a new key pair with the following command:
10+
## 1. Create Key Pair
1511

1612
```bash
1713
npx @capgo/cli key create
1814
```
1915

20-
This command will create a new key pair in your app; it is imperative to store the private key in a safe place. One must never commit the private key to source control nor share it with an untrusted party.
21-
22-
This command will also remove the old key from your Capacitor config, but it will not remove the old key files. The CLI keeps them to allow you to continue sending live updates for the apps that haven't received an app store update and are still using the old plugin. This facilitates the migration.
23-
24-
When you are asked by the migration, "Do you want to setup encryption with the new channel in order to support old apps and facilitate the migration?", please agree. It will add a new "defaultChannel" option to your Capacitor config. This will make your app use the channel "encryption_v2". This will ensure that the new encryption is used only by apps that support it. Apps that have not received an app store update will continue using the previous default channel.
16+
:::warning
17+
Store the private key securely. Never commit it to source control or share it with untrusted parties.
18+
:::
2519

26-
---
20+
This command:
21+
- Creates a new key pair in your app
22+
- Removes the old key from your Capacitor config
23+
- Keeps old key files for backward compatibility
2724

28-
Now, you need to build your JS bundle and upload it to the new channel. Please run the following command:
25+
## 2. Update Capacitor Config
2926

27+
When prompted "Do you want to setup encryption with the new channel in order to support old apps and facilitate the migration?", select yes. This adds a new `defaultChannel` option to your Capacitor config.
3028

31-
```bash
29+
```ts
30+
// capacitor.config.ts
31+
import { CapacitorConfig } from '@capacitor/cli';
3232

33-
npx @capgo/cli bundle upload --channel encryption_v2
33+
const config: CapacitorConfig = {
34+
appId: 'com.example.app',
35+
appName: 'Example App',
36+
plugins: {
37+
CapacitorUpdater: {
38+
// ... other options
39+
defaultChannel: 'encryption_v2' // New apps will use this channel
40+
}
41+
}
42+
};
3443

44+
export default config;
3545
```
3646

37-
---
47+
## 3. Upload Bundle to New Channel
3848

39-
Then, run this command to allow apps to self-assign to the channel "encryption_v2".
49+
```bash
50+
npx @capgo/cli bundle upload --channel encryption_v2
51+
```
4052

53+
## 4. Enable Self-Assignment
4154

4255
:::caution
43-
This is necessary for the new "defaultChannel" option to work.
56+
Required for the `defaultChannel` option to work
4457
:::
4558

46-
4759
```bash
48-
4960
npx @capgo/cli channel set encryption_v2 --self-assign
50-
5161
```
5262

53-
---
54-
55-
You can now run the app; it will use the new encryption system.
56-
57-
To upload the new JS bundle to the old channel, you only need to run the following command:
63+
## 5. Upload to Old Channel
5864

5965
```bash
6066
npx @capgo/cli bundle upload --channel production
6167
```
6268

63-
---
69+
:::tip
70+
Capacitor config is never uploaded to Capgo
71+
:::
6472

65-
You don't need to worry about Capacitor config, it is never uploaded to Capgo.
73+
## 6. Cleanup (After 3-4 Months)
6674

67-
When all users have updated their apps (it can take up to 3/4 months), you can remove the "defaultChannel" from your Capacitor config.
75+
Once all users have updated their apps:
6876

69-
And then, you can remove the old channel with the following command:
77+
1. Remove `defaultChannel` from your Capacitor config
78+
2. Delete the old channel:
7079

7180
```bash
7281
npx @capgo/cli channel delete encryption_v2
7382
```
7483

75-
---
76-
77-
After deleting the "encryption_v2" channel, all apps that use it as the default will start using the "production" channel.
84+
:::note
85+
Apps using `encryption_v2` as default will switch to `production` channel after deletion
86+
:::

‎src/content/docs/docs/live-updates/breaking-changes.md‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
---
2+
title: "Breaking Changes"
3+
description: "How to handle breaking changes with versioned channels"
4+
sidebar:
5+
order: 6
6+
---
7+
8+
This documentation explains how to handle breaking changes in your app using versioned channels. This approach allows you to maintain different versions of your app while ensuring users receive compatible updates.
9+
10+
## Example Scenario
11+
12+
Let's say you have:
13+
- App version 1.2.3 (old version) - uses production channel
14+
- App version 2.0.0 (new version with breaking changes) - uses v2 channel
15+
- Live update 1.2.4 (compatible with 1.2.3)
16+
- Live update 2.0.1 (compatible with 2.0.0)
17+
18+
## 1. Create Channel for New Version
19+
20+
```bash
21+
# Create channel for version 2.x
22+
npx @capgo/cli channel create v2
23+
```
24+
25+
## 2. Update Capacitor Config
26+
27+
```ts
28+
// capacitor.config.ts
29+
import { CapacitorConfig } from '@capacitor/cli';
30+
31+
const config: CapacitorConfig = {
32+
appId: 'com.example.app',
33+
appName: 'Example App',
34+
plugins: {
35+
CapacitorUpdater: {
36+
// ... other options
37+
defaultChannel: 'v2' // New apps will use v2 channel
38+
}
39+
}
40+
};
41+
42+
export default config;
43+
```
44+
45+
## 3. Upload Bundles to Respective Channels
46+
47+
```bash
48+
# Upload 1.2.4 to production channel (for 1.2.3 users)
49+
npx @capgo/cli bundle upload --channel production
50+
51+
# Upload 2.0.1 to v2 channel (for 2.0.0 users)
52+
npx @capgo/cli bundle upload --channel v2
53+
```
54+
55+
## 4. Enable Self-Assignment
56+
57+
```bash
58+
# Allow apps to self-assign to v2 channel
59+
npx @capgo/cli channel set v2 --self-assign
60+
```
61+
62+
## 5. Update App Code
63+
64+
Add version check in your app to assign users to the correct channel:
65+
66+
```ts
67+
// src/utils/updater.ts
68+
import { CapacitorUpdater } from '@capgo/capacitor-updater'
69+
70+
export async function setupUpdater() {
71+
const { appVersion } = await CapacitorUpdater.getCurrentVersion()
72+
const majorVersion = appVersion.split('.')[0]
73+
74+
// Version 1.x uses default production channel
75+
// Only assign v2 channel for version 2.x
76+
if (majorVersion === '2') {
77+
await CapacitorUpdater.setChannel('v2')
78+
}
79+
}
80+
```
81+
82+
## 6. Cleanup (After Migration)
83+
84+
Once all users have migrated to version 2.x:
85+
86+
1. Remove `defaultChannel` from your Capacitor config
87+
2. Delete the v2 channel:
88+
89+
```bash
90+
npx @capgo/cli channel delete v2
91+
```
92+
93+
:::tip
94+
This approach ensures users only receive updates compatible with their app version
95+
:::
96+
97+
:::warning
98+
Always test updates thoroughly in each channel before deployment
99+
:::
100+
101+
:::note
102+
You can safely delete the v2 channel in Capgo even if some users still have the channel override. They will automatically receive updates from the production channel instead.
103+
:::
104+
105+
## Maintaining Version 1.x Updates
106+
107+
To send updates compatible with version 1.x:
108+
109+
1. Create a git tag for version 1.x:
110+
```bash
111+
git tag v1.2.4
112+
git push origin v1.2.4
113+
```
114+
115+
2. Switch to the tag:
116+
```bash
117+
git checkout v1.2.4
118+
```
119+
120+
3. Build and upload to production channel:
121+
```bash
122+
npx @capgo/cli bundle upload --channel production
123+
```
124+
125+
:::tip
126+
Your main branch can continue targeting the latest version (2.x) while you maintain 1.x updates through git tags
127+
:::

0 commit comments

Comments
 (0)