guides/releasing/Release Workflow.md
Why: Vendored modules often ship bugfixes and new features during our SDK cycles and we generally want these as part of our product, as well.
How:
et update-vendored-module --list-outdated.main as a separate commit so that it's easy to revert later on if needed.Why: Various tools we will use throughout this process, including expo-cli, depend on the versioned schema hosted by www. We need to create the schema for this new SDK version.
How:
universe, cd server/www/xdl-schemas.cp UNVERSIONED-schema.json XX.X.X-schema.jsonmain in order to deploy to staging. It is also good to deploy to production, you can feel free to do this at any time as long as www is safe to deploy.Why: Various tools we will use throughout this process, including expo-cli, depend on data in the versions endpoint.
How:
et update-versions --sdkVersion XX.X.X --key expoVersion --value <expo package version>et update-versions --sdkVersion XX.X.X --key facebookReactVersion --value <react package version>et update-versions --sdkVersion XX.X.X --key facebookReactNativeVersion --value <react-native package version>et update-versions --sdkVersion XX.X.X --key expoReactNativeTag --value sdk-XX.X.XIf we're planning to update React Native version for the upcoming SDK then it should have been done before starting any of this!
Why:
We use our fork of React Native for building Expo Go, but it is not used otherwise. The submodule under react-native-lab/react-native is the source of truth for react-native version used throughout the expo/expo repository. Each SDK version has its own tagged version of React Native, even if it ends up being the exact same as upstream for that version or for a previous SDK release.
How:
react-native-lab/react-native submodule.react-native fork (sdk-XX typically, where XX is the major number of the SDK version).git tag -a 'sdk-XX.X.X' -m 'React Native X.Y.Z for Expo SDKXX' (where X.Y.Z is the React Native version and XX is the major number of SDK version), to make a tag for the latest commit in your local repo.git push --tags.Note: We may end up making changes to the react-native#sdk-XX branch at some point prior to release in order to fix issues that were encountered during QA and beta testing. We should delete and re-create the sdk-XX.X.X tag if this is done, so that when we do the final release the react-native version is sdk-XX.0.0.
Why: We provide some mocks of our native methods which are generated by traversing all the modules and its methods and making a configuration of all those methods with the number of arguments etc.
How:
next packages| Prerequisites |
|---|
| 0.5. Generate new mocks |
Why: We need to publish the unimodule packages to NPM so that we're able to prepare and test new project templates and people using bare workflow can use and test these packages before the final release. We use the next tag so people using the modules in bare workflow projects right now do not get these prereleased versions! We do this from main before cutting the release branch so that the version number bumps land on main first.
How:
et publish-packages. Talk to @tsapeta for more details/information.et sync-bundled-native-modules to sync the bundledNativeModules.json file with www.Why: We need to concatenate all new entries from packages' CHANGELOGs and add them to our main CHANGELOG file.
How:
et merge-changelogs --cut-off.sdk-XX project templates| Prerequisites |
|---|
0.6. Publish next packages |
Why: We also need to prepare project templates that are used when people run npx create-expo-app command and publish them to NPM registry to test in QA.
How:
et update-project-templates/et upt that checks all expo-template-* packages under templates directory and bumps dependency versions wherever possible – based on versions stored in packages/expo/bundledNativeModules.json for Expo modules and 3rd-party libraries, react-native fork with appropriate SDK version and expo package itself.create-expo-app at this point, just npx expo start them locally.et publish-templates/et ppt and answer to questions it asks. IMPORTANT: These versions should be tagged as sdk-XX and not latest. (If tagged as latest they will be used by default whenever anyone runs npx create-expo-app.)npx create-expo-app@latest --template blank@sdk-48.Why: We store separate versions of API reference docs for each SDK version. We need to version the docs as soon as we cut the release branch so that docs changes that land on main between cutting the release branch and the release date get applied to the new SDK version or not, as appropriate.
How:
et generate-docs-api-data to regenerate unversioned API data files before cutting new documentation version.et generate-sdk-docs --sdk XX.X.X to generate versioned docs for the new SDK.yarn run schema-sync XX (XX being the major version number) in docs directory and then change the schema import in pages/versions/<version>/config/app.mdx from unversioned to the new versioned schema file.version in package.json has NOT been updated to the new SDK version. SDK versions greater than the version in package.json will be hidden in production docs, and we do not want the new version to show up until the SDK has been released.| Prerequisites |
|---|
| All previous tasks |
Why: Since we are about to start QA, cutting a branch ensures that we aren't testing and versioning code that is changing under our feet. You can alternatively defer this until later if you don't have any reason to defer from main yet. Some later steps in this guide will need to be performed from the release branch.
How: After the SDK branch cutoff deadline, cut the sdk-XX branch from main and push it to the remote repo. You can continue to rebase the release branch on top of main until main starts to include commits that you do not want to pull in to the SDK branch, at which point you will need to cherry-pick.
Why: Smoke test and manual QA before versioning, so that we know that any regressions in versioning are due to the versioning process.
How:
Why: We really care about the quality of the code that we release for the users. Quality Assurance is the most important task during the release process, so please don't ignore any steps and also focus on things that have been changed/reworked/refactored in this cycle.
How:
Web is comparatively well-tested in CI, so a few manual smoke tests suffice for web QA.
cd apps/router-e2eyarn start and press w to open in the browser. Make sure the app loads successfully in development.Why: We need to publish native-component-list so other people can try it out (including app reviewers from Apple).
How:
apps/native-component-list and make sure its sdkVersion in app.json is set to the correct SDK (not UNVERSIONED).expo publish for both community and applereview accounts.native-component-list from applereview account and make sure it launches as expected.Why: Any changes that have been made to packages during QA / since the initial publish (step 0.6) still need to be published for bare workflow users (and managed, for TS changes).
How:
et publish-packages and publish all packages with changes.et sync-bundled-native-modules to sync the bundledNativeModules.json file with www.Why: We need to publish a new version of home in order to embed it in the Expo Go apps before building them.
How:
version and sdkVersion in apps/expo-go/app.json. Commit this change.yarn in apps/expo-go.et publish-dev-home. Commit the change to dev-home-config.json; do not commit any other changes from the script (in particular, if it changes home/app.json, do not commit those changes).exponent account (credentials in 1P). Then publish home with et publish-prod-home. This will publish home to production (update is unused in production) and write to two manifests and bundles (one each for iOS and Android) in the repo to be embedded in builds of Expo Go. Commit these changes.| Prerequisites |
|---|
| All previous tasks |
How:
iOS:
ios/Exponent/Supporting/Info.plist.et eas ios-client-build-and-submit from the project root folder and follow the prompt. This step can take 30+ minutes.Provide Export Compliance Information button and select "None of the algorithms mentioned above" in the dialog - we generally have not made changes to encryption.
ios.config.usesNonExemptEncryption to false in the Expo config. This will automatically set the export compliance to "None of the algorithms mentioned above" and will avoid displaying this prompt each time you are going through this process in App Store Connect.native-component-list published under applereview account. If you notice something important isn't working right, remove the app from review and re-do this process once it's resolved.Android:
versionName in android/app/build.gradle. Commit this to main and cherry-pick to the release branch. EAS Build will automatically manage the versionCode for you.et dispatch client-android-eas-release and wait for EAS Build to finish the APK building.| Prerequisites |
|---|
| 2.2. Build and submit |
Why: To allow developers to install Expo Go on the simulator (which doesn't have an App Store) we need to make a build for it, upload it to S3 servers and save its url and version on the versions endpoint. These builds are then downloaded and installed by the users using expo client:install:ios.
How:
et eas ios-simulator-build to trigger building Expo Go for iOS simulators on EAS.GITHUB_TOKEN=${GITHUB_TOKEN} et eas ios-simulator-upload to download the build artifact and upload it to the expo-go-releases GitHub repo. The GITHUB_TOKEN environment variable should have contents read/write access to the repo.et eas android-apk-build to trigger building Expo Go for Android APK on EAS.GITHUB_TOKEN=${GITHUB_TOKEN} et eas android-apk-upload to download the build artifact and upload it to the expo-go-releases GitHub repo. The GITHUB_TOKEN environment variable should have contents read/write access to the repo.et client-install -p {ios,android}.iosVersion/androidVersion iosUrl/androidUrl properties, eg:
et update-versions-endpoint -k 'iosVersion' -v '55.0.9' --rootet update-versions-endpoint -k 'iosUrl' -v 'https://github.com/expo/expo-go-releases/releases/download/Expo-Go-55.0.9/Expo-Go-55.0.9.tar.gz' --rootWhy: Each release works best with a specific image (Xcode/Node/npm/yarn/Java/NDK/etc version).
How:
Coordinate with the EAS Build team to do the following:
reactNativeImageMatchRules for Android and sdkVersionToDefaultBuildImage for iOS.| Prerequisites |
|---|
| All previous steps and App Store approval for TestFlight public beta |
Once everything above is completed and Apple has approved Expo Go (iOS) for the TestFlight public beta, the beta release is ready to go. Complete the following steps in order, ideally in fairly quick succession (not spread over multiple days).
Why: Make the docs available to beta testers and discoverable through the version selector, but not the default.
How: Merge the new SDK docs into main, but don't update the version in package.json yet. Instead, set the betaVersion field to the SDK version number, eg: "betaVersion": "40.0.0".
Why: These package versions are used by expo-cli in the install command to ensure that the proper versions of packages are installed in developers' projects.
How:
jesttypescript@babel/core@expo/config@types/react@types/react-domreact-native-webbabel-preset-expo@expo/config-plugins@expo/metro-config@expo/webpack-config@expo/prebuild-configexpo-modules-autolinkingmetroyarn why <package-name> to see which version is used by apps in the expo/expo repo. Generally the version numbers should use the caret (^) semver symbol, please refer to the semver symbol used for the package on the most recent release on the versions endpoint.Why: Ensure that the templates include the latest version of packages, so when we release the beta everything is up to date.
How: Follow 0.8. Publish sdk-XX project templates but be sure that the published template has the sdk-xx tag on npm in addition to next.
Why: It's time for everything that uses the production versions endpoint to know about this new SDK version!
How:
et update-versions-endpoint -s ${SDK_MAJOR_VERSION}.0.0 -k 'beta' -v 'true'et promote-versions-to-prody!How: Reach out to Cedric (@byCedric)
Why: We want interested developers to try it out and report any issues they encounter.
How:
Why: The beta period will run for approximately 1 week. During that time we should try to discover regressions and new bugs, fix them, and roll the fixes out to the beta users. The fixes will require repeating many of the previous steps, such as re-submitting an iOS build and re-deploying Turtle.
How:
Why: When the Expo Go app for iOS appears to be a good candidate for the final release, we should submit it for review in order to have an accepted release ready to deploy to the App Store in one button click when we proceed to the next stage. This should be ideally be done ~1-3 days before moving on to the final release, to account for review delays.
How:
Why: The release notes are a collaborative effort, we need contributions from folks who worked on the various improvements shipping with the release to draft brief explainations for them if they believe its worth calling out. It can take time for everyone to carve out time for this, so it's best to start it well before the final release in order to give people a week or so to contribute.
How:
If today is Friday: Wait until next week to finish the release :)
How:
et eas android-client-build-and-submit to trigger appropriate job on EAS Build. About 60 minutes later the update should be downloadable via Play Store.Why: Previously we've published packages and now that we have gone through beta testing and everything is good to go, we can promote those packages to latest on NPM.
How:
et promote-packages script.Why: Make the new SDK the default for everything that depends on the versions endpoint, eg: expo upgrade.
How:
et update-versions-endpoint -s ${SDK_MAJOR_VERSION}.0.0 -k 'beta' --deleteet promote-versions-to-prody!Why: Once the new SDK is available publicly, we should switch to using it by default on Snack.
How: Reach out to Cedric
Why: Show the new docs by default now that the SDK is being released!
How:
version field docs/package.json to match the new SDK version, delete the betaVersion field, and push to main.Why: We need to make sure the templates point to the latest versions of our packages and update the tags on npm so they will be used by default with npx create-expo-app.
How:
npx create-expo-app at this point, just run npx expo start to run them locally.et publish-templates/et ppt and answer to questions it asks. IMPORTANT: These versions should be tagged as latest and sdk-xx where xx is the major version for the SDK being released.| Prerequisites |
|---|
| All previous tasks |
This should be ready to publish immediately after the previous step is finished!
Why: We want to announce it on social media once the new SDK is out. We usually start from the blog post on Medium that describes the changes that come up since the previous release, how to upgrade from the previous SDK version, etc.
How:
Why: A few places in our infrastructure need to know about the release notes once they're published.
How:
et update-versions --sdkVersion XX.X.X --key releaseNoteUrl --value <url> and et promote-versions-to-produpgrading-expo-sdk-walkthrough docs page, commit and push to main, and deploy docs again.Why: A few expo-cli commands use this flag to determine which SDK versions are still supported.
How: et update-versions --sdkVersion XX.X.X --deprecated true, then et promote-versions