Ota docs update (#8279)
* Begin edits * Add alert * Add new assets * Refactor OTA docs * Format
This commit is contained in:
Eric Bailey
+120
-77
@@ -1,95 +1,138 @@
|
||||
# OTA Deployments
|
||||
|
||||
## Overview
|
||||
## Automatic internal OTAs
|
||||
|
||||
|
||||
|
||||
## Internal Deployments
|
||||
|
||||
Internal OTA deployments should be performed automatically upon all merges into main. In cases where the fingerprint
|
||||
diff results in incompatible native changes, a new client build will automatically be ran and deployed to TestFlight
|
||||
OTA deployments to TestFlight/APK installs happen automatically upon all merges
|
||||
into main. In cases where the fingerprint diff shows incompatible native
|
||||
changes, a new client build will automatically be ran and deployed to TestFlight
|
||||
(iOS) or delivered in Slack (Android).
|
||||
|
||||
## Production Deployments
|
||||
## Production OTAs
|
||||
|
||||
### Prerequisites
|
||||
Production OTAs can only update the JavaScript bundle. Changes to native modules
|
||||
must be done as a full release cycle through the app stores.
|
||||
|
||||
- Find the latest production build number for both iOS and Android in Slack. These are listed in #client-builds
|
||||
- Production builds always send the Version Number and Build Number in the Slack message. Search for the latest
|
||||
production version number, and you should find the correct information.
|
||||
|
||||
|
||||
> [!TIP]
|
||||
> If you're using a TestFlight build, in order to reference the correct build
|
||||
> number and to verify the success of an OTA, you will need to delete the
|
||||
> TestFlight app itself, delete the Bluesky app entirely, and re-install from
|
||||
> the App Store.
|
||||
|
||||
- It may also be useful to check the current production clients for these values. This will also help for testing. Note
|
||||
that you will need to _fully_ remove the existing internal client build from your device, otherwise the given values in
|
||||
the app may differ from the actual production values.
|
||||
### 1. Find the build numbers
|
||||
|
||||
|
||||
Find the latest production build numbers for iOS and Android in Slack. These are
|
||||
spit out into `#bot-client-builds` after each release. You can also find this
|
||||
information under the `About` section in app settings.
|
||||
|
||||
- You should have signed in to EAS locally through npx eas login. You will need to modify the build number in a
|
||||
subsequent step.
|
||||
- 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
|
||||
- Note: If the commit is not properly tagged, then the OTA deployment will simply fail since the GitHub Action will
|
||||
not be able to find a commit to fingerprint and diff against.
|
||||
| Slack | In app |
|
||||
| ----- | ------ |
|
||||
|  |  |
|
||||
|
||||
### Preparation
|
||||
### 2. Ensure the release is tagged
|
||||
|
||||
- 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
|
||||
client. Name this branch `1.X.0-ota-1`
|
||||
- If a deployment has been made previously for this release, increment the branch name, i.e. `1.x.0-ota-2`
|
||||
- If necessary, cherry-pick the commit(s) that you wish to deploy
|
||||
- Ensure that the package.json’s version field is set to the appropriate value. As long as used the correct git tag
|
||||
to create your branch from, this should be properly set.
|
||||
You need to ensure that the latest release was properly tagged using the format
|
||||
`1.X.0`. If the commit is not properly tagged, then the OTA deployment will
|
||||
simply fail since the GitHub Action will not be able to find a commit to
|
||||
fingerprint and diff against.
|
||||
|
||||
### Deployment
|
||||
### 3. Create an OTA branch
|
||||
|
||||
- Update the build number through EAS to match the build numbers of the
|
||||
production iOS/Android apps
|
||||
- Note: This isn’t strictly necessary, but having a step that takes you off of GitHub and into the terminal provides
|
||||
a little “friction” to avoid fat fingering a release. Since there are legitimate reasons to just “click and deploy”
|
||||
for internal builds, I felt it useful to make sure it doesn’t accidentally become a prod deployment.
|
||||
- Set the build numbers to the values found in the prerequisite steps. Again, this should be the
|
||||
build number for the current production release you want to deploy for.
|
||||
- `npx eas build:version:set -p ios`
|
||||
- `npx eas build:version:set -p android`
|
||||
- These steps should spit out what the current build number is, save those values
|
||||
for later too
|
||||
- Run the deployment
|
||||
- Navigate to https://github.com/bluesky-social/social-app/actions/workflows/bundle-deploy-eas-update.yml
|
||||
- Select the “Run Workflow” dropdown
|
||||
|
||||
|
||||
|
||||
- Select the branch for the deployment you are releasing.
|
||||
|
||||
|
||||
|
||||
- Double check the branch selection.
|
||||
- Select the production channel
|
||||
- Enter the version for the client you are releasing to, i.e. 1.80.0
|
||||
- Note: If you do enter an incorrect version here, the deployment will either:
|
||||
- Fail because the action cannot find a commit with your misentered version
|
||||
- Succeed - but with no users receiving the update. This is because the version you entered will not properly
|
||||
correlate to a _build number_ as well, so no clients in the wild will be able to receive the update.
|
||||
|
||||
|
||||
|
||||
- Triple check the branch selection.
|
||||
- You selected the correct branch
|
||||
- You selected the "Production" channel
|
||||
- You entered the correct version in the format of `1.X.0`.
|
||||
- Press “Run Workflow”
|
||||
Create a branch based off the last commit that was deployed in the most recent
|
||||
release. This could be the commit that was tagged `1.x.0`, or a later commit,
|
||||
but it **needs to be the tip of the latest production release** in any case.
|
||||
Double check yourself by ensuring that the `version` in `package.json` matches
|
||||
what's in the latest release.
|
||||
|
||||
In about five minutes, the new deployment should be available for download. To test:
|
||||
This new OTA branch should follow the format `1.X.0-ota-1`. If one or more OTAs
|
||||
have already been deployed for this release, incremement the branch name e.g.
|
||||
`1.x.0-ota-2`.
|
||||
|
||||
- Remove the internal build of the app from your device
|
||||
- Download the app from the App Store/Google Play
|
||||
- Launch the app once and wait approximately 15 seconds
|
||||
- Relaunch the app
|
||||
- Check the Settings page and scroll to the bottom. The commit hash should now be the latest commit on your deployed branch.
|
||||
### 4. Add commits to the OTA branch
|
||||
|
||||
### Post Deployment
|
||||
Cherry pick in the commits that need to be deployed on top of the most recent
|
||||
release or OTA.
|
||||
|
||||
- Reset both platforms build numbers to what they were before the OTA
|
||||
deployment. These values should have been logged by the EAS CLI when you
|
||||
reset them to the production values prior to OTA.
|
||||
### 5. Manually set build numbers
|
||||
|
||||
Log in to the EAS CLI with `eas login` and manually set the build numbers to the
|
||||
values you found in **Step 1**.
|
||||
|
||||
```sh
|
||||
> npx eas build:version:set -p ios
|
||||
>
|
||||
> Project @blueskysocial/bluesky with bundle identifier "xyz.blueskyweb.app" is configured with buildNumber 1011.
|
||||
> ✔ What version would you like to set? … 1009
|
||||
>
|
||||
> npx eas build:version:set -p android
|
||||
>
|
||||
> Project @blueskysocial/bluesky with application ID "xyz.blueskyweb.app" is configured with versionCode 641.
|
||||
> ✔ What version would you like to set? … 639
|
||||
```
|
||||
|
||||
👉 **Save the previous values,** in this case `1011` and `641`, so you can reset
|
||||
them after the OTA completes.
|
||||
|
||||
### 6. Run the GitHub actions
|
||||
You'll need to run two separate actions: one to deploy the iOS/Android OTA
|
||||
itself, and one to build the web Docker container.
|
||||
|
||||
**For the iOS/Android OTA,** head to [Actions > Bundle and Deploy EAS
|
||||
Update](https://github.com/bluesky-social/social-app/actions/workflows/bundle-deploy-eas-update.yml)
|
||||
and run the action.
|
||||
|
||||
| Steps | |
|
||||
| ----- | --- |
|
||||
| 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" |  |
|
||||
|
||||
> [!NOTE]
|
||||
> If you do enter an incorrect version here, the deployment will either:
|
||||
> - Fail, because the action cannot find a commit with your misentered version
|
||||
> - Succeed, but with no users receiving the update. This is because the version
|
||||
> you entered will not properly correlate to a _build number_ as well, so no
|
||||
> clients in the wild will be able to receive the update.
|
||||
|
||||
**For web,** head to [Actions >
|
||||
build-and-push-bskyweb-aws](https://github.com/bluesky-social/social-app/actions/workflows/build-and-push-bskyweb-aws.yaml)
|
||||
and run the action.
|
||||
|
||||
| Steps | |
|
||||
| ----- | --- |
|
||||
| Select your OTA branch `1.x.0-ota-x` and click "Run workflow" |  |
|
||||
|
||||
### 7. Deploy web
|
||||
|
||||
Once the web Docker container build finishes, go to your `1.x.0-ota-x` branch,
|
||||
copy the most recent commit hash. Post this hash in `#ops-deploys` and request
|
||||
someone with web deploy access deploy the built container.
|
||||
|
||||
### 8. Confirm successful deployment
|
||||
|
||||
In about five minutes, the new deployment should be deployed and devices will
|
||||
begin downloading and installing in the background.
|
||||
|
||||
To confirm this, as mentioned above, you must completely clear the TestFlight
|
||||
build from your device and re-install from the App Store. Then, you'll need to:
|
||||
- Launch the app (or quit and reopen) and wait ~15s for the download to complete
|
||||
- Quit and reopen the app
|
||||
- Check the `Settings > About` page and confirm the has matches the most recent has on your OTA branch
|
||||
|
||||
### 9. Reset build numbers
|
||||
|
||||
Grab the build numbers you saved in **Step 5** and reverse the EAS CLI commands
|
||||
to reset the build numbers.
|
||||
|
||||
```sh
|
||||
> npx eas build:version:set -p ios
|
||||
>
|
||||
> Project @blueskysocial/bluesky with bundle identifier "xyz.blueskyweb.app" is configured with buildNumber 1009.
|
||||
> ✔ What version would you like to set? … 1011
|
||||
>
|
||||
> npx eas build:version:set -p android
|
||||
>
|
||||
> Project @blueskysocial/bluesky with application ID "xyz.blueskyweb.app" is configured with versionCode 639.
|
||||
> ✔ What version would you like to set? … 641
|
||||
```
|
||||
|
||||
## Overview diagram
|
||||
|
||||
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 220 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 85 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 558 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 48 KiB |
Reference in New Issue
Block a user