quilling.dev
An ATproto social media client -- with an independent Appview.
Ota docs update (#8279)
* Begin edits
* Add alert
* Add new assets
* Refactor OTA docs
* Format
authored by
Eric Bailey
and committed by
GitHub
d992b277
6f44abee
+119
-76
docs/deploy-ota.md
+119
-76
docs/deploy-ota.md
···
1
1
# OTA Deployments
2
2
3
-
## Overview
3
+
## Automatic internal OTAs
4
+
5
+
OTA deployments to TestFlight/APK installs happen automatically upon all merges
6
+
into main. In cases where the fingerprint diff shows incompatible native
7
+
changes, a new client build will automatically be ran and deployed to TestFlight
8
+
(iOS) or delivered in Slack (Android).
9
+
10
+
## Production OTAs
11
+
12
+
Production OTAs can only update the JavaScript bundle. Changes to native modules
13
+
must be done as a full release cycle through the app stores.
14
+
15
+
> [!TIP]
16
+
> If you're using a TestFlight build, in order to reference the correct build
17
+
> number and to verify the success of an OTA, you will need to delete the
18
+
> TestFlight app itself, delete the Bluesky app entirely, and re-install from
19
+
> the App Store.
4
20
5
-
21
+
### 1. Find the build numbers
22
+
23
+
Find the latest production build numbers for iOS and Android in Slack. These are
24
+
spit out into `#bot-client-builds` after each release. You can also find this
25
+
information under the `About` section in app settings.
26
+
27
+
| Slack | In app |
28
+
| ----- | ------ |
29
+
|  |  |
6
30
7
-
## Internal Deployments
31
+
### 2. Ensure the release is tagged
8
32
9
-
Internal OTA deployments should be performed automatically upon all merges into main. In cases where the fingerprint
10
-
diff results in incompatible native changes, a new client build will automatically be ran and deployed to TestFlight
11
-
(iOS) or delivered in Slack (Android).
33
+
You need to ensure that the latest release was properly tagged using the format
34
+
`1.X.0`. If the commit is not properly tagged, then the OTA deployment will
35
+
simply fail since the GitHub Action will not be able to find a commit to
36
+
fingerprint and diff against.
12
37
13
-
## Production Deployments
38
+
### 3. Create an OTA branch
14
39
15
-
### Prerequisites
40
+
Create a branch based off the last commit that was deployed in the most recent
41
+
release. This could be the commit that was tagged `1.x.0`, or a later commit,
42
+
but it **needs to be the tip of the latest production release** in any case.
43
+
Double check yourself by ensuring that the `version` in `package.json` matches
44
+
what's in the latest release.
16
45
17
-
- Find the latest production build number for both iOS and Android in Slack. These are listed in #client-builds
18
-
- Production builds always send the Version Number and Build Number in the Slack message. Search for the latest
19
-
production version number, and you should find the correct information.
20
-
21
-
46
+
This new OTA branch should follow the format `1.X.0-ota-1`. If one or more OTAs
47
+
have already been deployed for this release, incremement the branch name e.g.
48
+
`1.x.0-ota-2`.
49
+
50
+
### 4. Add commits to the OTA branch
51
+
52
+
Cherry pick in the commits that need to be deployed on top of the most recent
53
+
release or OTA.
54
+
55
+
### 5. Manually set build numbers
56
+
57
+
Log in to the EAS CLI with `eas login` and manually set the build numbers to the
58
+
values you found in **Step 1**.
59
+
60
+
```sh
61
+
> npx eas build:version:set -p ios
62
+
>
63
+
> Project @blueskysocial/bluesky with bundle identifier "xyz.blueskyweb.app" is configured with buildNumber 1011.
64
+
> ✔ What version would you like to set? … 1009
65
+
>
66
+
> npx eas build:version:set -p android
67
+
>
68
+
> Project @blueskysocial/bluesky with application ID "xyz.blueskyweb.app" is configured with versionCode 641.
69
+
> ✔ What version would you like to set? … 639
70
+
```
71
+
72
+
👉 **Save the previous values,** in this case `1011` and `641`, so you can reset
73
+
them after the OTA completes.
74
+
75
+
### 6. Run the GitHub actions
76
+
You'll need to run two separate actions: one to deploy the iOS/Android OTA
77
+
itself, and one to build the web Docker container.
78
+
79
+
**For the iOS/Android OTA,** head to [Actions > Bundle and Deploy EAS
80
+
Update](https://github.com/bluesky-social/social-app/actions/workflows/bundle-deploy-eas-update.yml)
81
+
and run the action.
82
+
83
+
| Steps | |
84
+
| ----- | --- |
85
+
| Select your OTA branch `1.x.0-ota-x`, select `production` in the dropdown, enter the git tag of the latest release `1.x.0`, and click "Run workflow" |  |
86
+
87
+
> [!NOTE]
88
+
> If you do enter an incorrect version here, the deployment will either:
89
+
> - Fail, because the action cannot find a commit with your misentered version
90
+
> - Succeed, but with no users receiving the update. This is because the version
91
+
> you entered will not properly correlate to a _build number_ as well, so no
92
+
> clients in the wild will be able to receive the update.
93
+
94
+
**For web,** head to [Actions >
95
+
build-and-push-bskyweb-aws](https://github.com/bluesky-social/social-app/actions/workflows/build-and-push-bskyweb-aws.yaml)
96
+
and run the action.
22
97
23
-
- It may also be useful to check the current production clients for these values. This will also help for testing. Note
24
-
that you will need to _fully_ remove the existing internal client build from your device, otherwise the given values in
25
-
the app may differ from the actual production values.
98
+
| Steps | |
99
+
| ----- | --- |
100
+
| Select your OTA branch `1.x.0-ota-x` and click "Run workflow" |  |
26
101
27
-
102
+
### 7. Deploy web
28
103
29
-
- You should have signed in to EAS locally through npx eas login. You will need to modify the build number in a
30
-
subsequent step.
31
-
- Ensure that the commit the initial client was cut from is properly tagged in git. The tag should be in the format of 1.X.0
32
-
- Note: If the commit is not properly tagged, then the OTA deployment will simply fail since the GitHub Action will
33
-
not be able to find a commit to fingerprint and diff against.
104
+
Once the web Docker container build finishes, go to your `1.x.0-ota-x` branch,
105
+
copy the most recent commit hash. Post this hash in `#ops-deploys` and request
106
+
someone with web deploy access deploy the built container.
34
107
35
-
### Preparation
108
+
### 8. Confirm successful deployment
36
109
37
-
- Create a new branch from the git tag that the initial release was cut from if no OTA deployment has been made yet for this
38
-
client. Name this branch `1.X.0-ota-1`
39
-
- If a deployment has been made previously for this release, increment the branch name, i.e. `1.x.0-ota-2`
40
-
- If necessary, cherry-pick the commit(s) that you wish to deploy
41
-
- Ensure that the package.json’s version field is set to the appropriate value. As long as used the correct git tag
42
-
to create your branch from, this should be properly set.
110
+
In about five minutes, the new deployment should be deployed and devices will
111
+
begin downloading and installing in the background.
43
112
44
-
### Deployment
113
+
To confirm this, as mentioned above, you must completely clear the TestFlight
114
+
build from your device and re-install from the App Store. Then, you'll need to:
115
+
- Launch the app (or quit and reopen) and wait ~15s for the download to complete
116
+
- Quit and reopen the app
117
+
- Check the `Settings > About` page and confirm the has matches the most recent has on your OTA branch
45
118
46
-
- Update the build number through EAS to match the build numbers of the
47
-
production iOS/Android apps
48
-
- Note: This isn’t strictly necessary, but having a step that takes you off of GitHub and into the terminal provides
49
-
a little “friction” to avoid fat fingering a release. Since there are legitimate reasons to just “click and deploy”
50
-
for internal builds, I felt it useful to make sure it doesn’t accidentally become a prod deployment.
51
-
- Set the build numbers to the values found in the prerequisite steps. Again, this should be the
52
-
build number for the current production release you want to deploy for.
53
-
- `npx eas build:version:set -p ios`
54
-
- `npx eas build:version:set -p android`
55
-
- These steps should spit out what the current build number is, save those values
56
-
for later too
57
-
- Run the deployment
58
-
- Navigate to https://github.com/bluesky-social/social-app/actions/workflows/bundle-deploy-eas-update.yml
59
-
- Select the “Run Workflow” dropdown
60
-
61
-
62
-
63
-
- Select the branch for the deployment you are releasing.
64
-
65
-
66
-
67
-
- Double check the branch selection.
68
-
- Select the production channel
69
-
- Enter the version for the client you are releasing to, i.e. 1.80.0
70
-
- Note: If you do enter an incorrect version here, the deployment will either:
71
-
- Fail because the action cannot find a commit with your misentered version
72
-
- Succeed - but with no users receiving the update. This is because the version you entered will not properly
73
-
correlate to a _build number_ as well, so no clients in the wild will be able to receive the update.
74
-
75
-
76
-
77
-
- Triple check the branch selection.
78
-
- You selected the correct branch
79
-
- You selected the "Production" channel
80
-
- You entered the correct version in the format of `1.X.0`.
81
-
- Press “Run Workflow”
119
+
### 9. Reset build numbers
82
120
83
-
In about five minutes, the new deployment should be available for download. To test:
121
+
Grab the build numbers you saved in **Step 5** and reverse the EAS CLI commands
122
+
to reset the build numbers.
84
123
85
-
- Remove the internal build of the app from your device
86
-
- Download the app from the App Store/Google Play
87
-
- Launch the app once and wait approximately 15 seconds
88
-
- Relaunch the app
89
-
- Check the Settings page and scroll to the bottom. The commit hash should now be the latest commit on your deployed branch.
124
+
```sh
125
+
> npx eas build:version:set -p ios
126
+
>
127
+
> Project @blueskysocial/bluesky with bundle identifier "xyz.blueskyweb.app" is configured with buildNumber 1009.
128
+
> ✔ What version would you like to set? … 1011
129
+
>
130
+
> npx eas build:version:set -p android
131
+
>
132
+
> Project @blueskysocial/bluesky with application ID "xyz.blueskyweb.app" is configured with versionCode 639.
133
+
> ✔ What version would you like to set? … 641
134
+
```
90
135
91
-
### Post Deployment
136
+
## Overview diagram
92
137
93
-
- Reset both platforms build numbers to what they were before the OTA
94
-
deployment. These values should have been logged by the EAS CLI when you
95
-
reset them to the production values prior to OTA.
138
+
docs/img/ios_settings_about.jpeg
docs/img/ios_settings_about.jpeg
This is a binary file and will not be displayed.
docs/img/ota_action.png
docs/img/ota_action.png
This is a binary file and will not be displayed.
docs/img/slack_client_builds.jpeg
docs/img/slack_client_builds.jpeg
This is a binary file and will not be displayed.
docs/img/web_action.png
docs/img/web_action.png
This is a binary file and will not be displayed.