Skip to content
This repository was archived by the owner on Dec 14, 2021. It is now read-only.

Commit 6a292be

Browse files
author
Elise Richards
committed
Update docs to reflect latest release process
1 parent 2218ebd commit 6a292be

1 file changed

Lines changed: 99 additions & 89 deletions

File tree

‎docs/releases.md‎

Lines changed: 99 additions & 89 deletions
Original file line numberDiff line numberDiff line change
@@ -3,116 +3,134 @@
33
Some assumptions:
44

55
- `master` is the default branch and is production-ready
6-
- non-'master' and non-'production' branches run the "primary" workflow which signs a "Debug" variant
7-
- though, users with access can manually "Start" a "deploy" build against a branch from the bitrise UI
8-
- commits made to `master` and `production` are built and pass in [bitrise][1]
6+
- Non-'master' and non-'production' branches run the "primary" workflow on Bitrise which signs a "Debug" variant
7+
- [Bitrise][1] access is currently private and email-restricted
8+
- Users with access can [manually start][4] a "deploy" build against a specified branch from the Bitrise UI
9+
- Commits made to `master` and `production` are built and pass in [Bitrise][1]
910
- the "deploy" workflow in bitrise runs and signs a "Release" variant APK
10-
- bitrise will test, build, and sign the APK for every build on every branch
11-
- `production` is our public release branch and may not match `master`
12-
- ideally, `production` will perfectly reproduce master
13-
- but if `master` is in an un-releasable state, we cherry-pick commits to this branch
14-
- this is an exception rather than the preferred maintenance method
15-
- no automated uploads to Google Play Console occur, manual artifact uploads (from bitrise's signed Release artifacts) are required for internal, closed, open, and production releases
16-
- Play Store has Internal (core team, email-restricted), Alpha (closed, email-restricted), and Production (everyone!) release channels configured
17-
- currently, no plans exist for "external" testers nor "Open" release channels
18-
- in the future we may create an open Beta testing channel to allow anyone outside of Mozilla to help us test in-progress work
19-
20-
## Distributing Builds through bitrise (primary = branch, deploy = master)
11+
- Bitrise will test, build, and sign the APK for every build on every branch
12+
- No automated uploads to Google Play Console occur. Manual artifact uploads (from a signed Release artifact) are required for internal, closed, open, and production releases
13+
- The Google Play Store has Internal (core team, email-restricted), Alpha (closed, email-restricted), Beta, and Production release channels configured
14+
15+
## Distributing Builds through Bitrise (primary = branch, deploy = master)
2116

2217
_all commits on all branches and pull requests are automatically built_
2318

24-
1. Push to the git branch available on GitHub.com and open a pull request
25-
2. Open [bitrise][1] from a mobile device and browse to the build
26-
- bitrise access is currently private and email-restricted
19+
1. Push all changes to the branch on GitHub and open a [pull request][3] (base: `master`, compare: your branch)
20+
2. Open [Bitrise][1] and browse to the build
21+
3. From the “Apps & Artifacts” tab, download the APK
2722

28-
## Preparing a Release (for Internal, Alpha, or Production via Play Store)
23+
## Preparing a Release (Google Play Store)
2924

3025
### Collect necessary identifiers for the new build
3126

27+
2. Before **public** release:
28+
- Make sure no open "localization strings" Pull Requests are open
29+
- Update the `versionName` and `versionCode` values in `app/build.gradle`
30+
- Create a [milestone][5] in GitHub to track the issues to be released
31+
- Create a PI request in Jira for the QA team to complete before releasing to production ([example][6])
32+
3. After **public** release:
33+
- Consider filing an issue for the next sprint/release to update to the latest dependencies (for example, application-services and/or android-components)
34+
- Consider running `mkdocs gh-deploy` so the latest `docs` are also published to the GitHub pages website
35+
- Also update the value in the `list_cell_setting_appversion.xml` layout to _the exact same version_
36+
- Make sure the `app-mapping.txt` (ProGuard rules) is uploaded to Sentry as part of the process earlier, do it now if not so your error reports are legible.
37+
38+
## Create a release branch and prepare the production branch
39+
3240
Before you can begin a new production release, it is necessary to take the following steps into consideration:
3341

34-
1. Find the current production version number. Using the strategy below, increment the version number to identify the state of the new release.
42+
1. Find the current production version number. Using the strategy below, increment the version number to identify the state of the new release in `app/build.gradle`.
3543
- **Choosing a new release version number**
3644
- Build versions are defined using a three-place value, `X.X.X`. Each number in the version is incremented based on the priority of the version being released.
3745
- For normally scheduled releases, the left-most value is incremented and the following two numbers "reset" to zero.
3846
- Example: after release `2.1.0`, the next normally scheduled release would be version `3.0.0`.
3947
- For smaller consecutive builds that come after a scheduled release (this could be bug fixes, etc.), the left-most value is maintained while the middle number is incremented.
4048
- Example: after release `3.0.0`, a version may be titled `3.1.0`.
41-
- For emergency hotfix/high priority/not scheduled releases, we may want to do a "point release". In this case, the left two values stay the same and the right-most value is incremented.
49+
- For emergency hotfix, high priority, or not-scheduled releases, we may want to do a "point release". In this case, the left two values stay the same and the right-most value is incremented.
4250
- Example: after release `3.1.0`, an emergency hotfix release would be titled `3.1.1`.
43-
2. Before **public** release:
44-
- make sure no open "localization strings" Pull Requests are open
45-
3. After **public** release:
46-
- Consider filing an issue for the next sprint/release to update to the latest dependencies (application-services, for example)
47-
- Consider running `mkdocs gh-deploy` so the latest `docs` are also published to the GitHub pages website
48-
- Consider changing the version to the next major/planned release version (depending on the future plans). Update the `versionName` value (and `versionCode` if applicable) in `app/build.gradle`
49-
- Also update the value in the `list_cell_setting_appversion.xml` layout to _the exact same version_
50-
- Make sure the `app-mapping.txt` (ProGuard rules) is uploaded to Sentry as part of the process earlier, do it now if not so your error reports are legible.
51+
2. Update the release notes under `docs/release-notes.md`
52+
- Determine the next build number (see above, "Choosing a new release version number") and include it in release notes
53+
- Create a pull request for the release notes into the `master` branch and get approval
54+
- Merge the release notes to `master` branch
55+
3. Next, we will choose a new version code and update the `versionCode` field in `app/build.gradle`.
56+
- Version codes will correspond to the build number on Bitrise
57+
- Example: [build #5931][7]
58+
- Make sure that both version code and version number are updated in the `build.gradle` file on `master`
59+
4. For each major release (a normally scheduled release where the left-most value of the build number, `X.X.X`, is incremented), create a new branch from `master` based on the following naming convention:
60+
- The new branch will follow this pattern: `release-#.x`, where # corresponds to the left-most build number of `X.X.X`
61+
- For example, `release-v3.x` for version `3.0.0`, `release-v4.x` for version `4.0.0`, etc.
62+
5. Additionally, create another new branch from `master` following the naming convention `release-v1.1.2` for a new version called `1.1.2`
63+
- In this scheme, all of the versions starting with `X.0.0` will have a specific “snapshot” branch (e.g. `release-v1.1.2`), and the `release-v#.x` branch will reflect the current state of production.
64+
6. At this point, ensure that all changes and branches are pushed upstream to GitHub
65+
- The new `release-v#.x` branch should match `master`, with new release notes, version code, and version number
66+
- The new `release-v#.#.#` branch should match both the current state of `master` and `release-v#.x` (remember: the `release-v#.x` branch will always reflect the most up-to-date state of the production app)
67+
68+
## Create the Play Store release
69+
70+
### Tag the release
71+
1. Create a tag from the `release-v#.x` branch matching the format: `release-vX.X.X-RC-#` (RC = release candidate)
72+
- We may have more than one release candidate for each version
73+
- Include the Bitrise build number (aka version code) in the tag message
74+
- Command line: `git tag -a -s release-v3.3.0-RC-1 -m “3.3.0 (Build 5783)”`, where “Build 5783” corresponds to the Bitrise build number (version code)
75+
- Example:
76+
- `release-v1.2.0-RC-1` is major version 1.2.0, release candidate 1
77+
- `release-v1.2.0-RC-2` is major version 1.2.0, the second version of the release candidate
78+
2. Create another tag from the `release-v#.x` branch for the “major” version of the release:
79+
- Command line: `git tag -a -s release-v3.3.0 -m “3.3.0 (Build 5783)”`
80+
3. Push the tags to GitHub
81+
- `git push --tags` will push all local tags to origin
5182

52-
### Create a release branch and prepare the production branch
83+
### Create the APK and Release
84+
1. From Bitrise, [manually start][4] a "deploy" build against the major release branch
85+
- “Start/Schedule a Build” -> Branch: `release-v3.x` -> Message: “3.3.0 (Build 5783)” -> Workflow: “Deploy” -> “Start Build”
86+
- **Important**: wait for this build to finish running. If the build is not green, you cannot release it.
87+
2. Download the `-signed.apk` from Bitrise (found in "Apps & Artifacts" tab on the successful deploy build) and add it as an attachment to the Release on GitHub
88+
- **Important:** Open the `-signed.apk` on your device/emulator and confirm release build does not allow screenshots and does not expose the contents of the app
89+
3. Also download the `app-mapping.txt` from the “Apps & Artifacts” tab on Bitrise
90+
- Suggestion: rename the file to `app-mapping-BUILDNUMBER.txt` to make it less generic
91+
- This will be used by Proguard, Sentry, and the Play Console later to deobfuscate the apk
92+
4. Create a new [Release][9] on GitHub
93+
- [Draft a new release][10] using the major tag version that you created (e.g. `release-v3.3.0`)
94+
- The release title will match this format: “3.3.0 (Build 5784)”
95+
- Mark this as a "pre-release" until PI requests are finished
96+
- Copy the release notes into the release description
97+
- Upload the `-signed.apk` as an attachment
5398

54-
1. Update the release notes under `docs/release-notes.md`
55-
- determine the next build number (see above, "Choosing a new release version number") and include it in release notes
56-
- create a pull request into the `master` branch and get approval
57-
- merge the release notes to `master` branch
58-
- this will result in a release build matching the build number provided
59-
2. Create a new branch from `master` for this release (following the naming convention `release-v1.1.2` for a new version called `1.1.2`)
60-
3. Update the `versionCode` and `versionName` values in the `build.gradle` file to match the new version number
61-
4. Create a pull request from this release branch to `production`
62-
- https://github.com/mozilla-lockwise/lockwise-android/compare/production...release-vYOURVERSION
63-
- once the Bitrise checks pass, merge the branch into `production`
99+
## Create the release on the Play Console
64100

65-
### Create the Play Store release
101+
### Distributing Builds through Play Store (Internal, Alpha, Beta)
66102

67-
1. Create a tag from `production` matching the format: `major.minor.patch.buildNumber`
68-
- Example:
69-
- `1.2.1399` is major version 1.2, Bitrise build #1399
70-
- `1.3.1.1624` is major version 1.3 with 1 patch release, Bitrise build #1624
71-
- `git tag -a -s 1.3.1.1624 -m "1.3.1 (Build 1624)"`
72-
2. Push the tag to GitHub and create a corresponding "Release" on GitHub
73-
- `git push --tags` will push all local tags to origin
74-
- mark this as a "pre-release" until PI requests are finished
75-
- copy the release notes to the "Release" on GitHub
76-
3. Download the `-signed.apk` from Bitrise (found in "Apps & Artifacts" tab on the successful production deploy build) and attach it to the Release on GitHub
77-
- **Important:** Open the `-signed.apk` and confirm release build does not allow screenshots and does not expose the contents of the app in the switcher
78-
4. Upload the `-signed.apk` to the [Play Console][2]:
103+
_All builds must be manually uploaded from bitrise to Play Store Console as an artifact aka "New Release" in the "Preparing" instructions above. Only mobile engineering managers and Release Management team members (See #release-coordination) have access to create new non-production releases._
104+
105+
1. Upload the `-signed.apk` to the [Play Console][2]:
79106
- browse to "Release Management" > "App Releases" > "Internal test track" > "Manage"
80-
- "Create Release" and upload the signed APK, set the version to match the github tag (for example: `1.2.1339`) then "Review" and the build will be immediately available to the core team
81-
5. Download the `app-mapping.txt` (ProGuard rules) from Bitrise
82-
- Suggestion: rename the file to `app-mapping-BUILDNUMBER.txt` to make it less generic
83-
- This will be used in step 8
84-
6. Create a file named `AndroidManifest-YOURBUILDNUMBER.xml` in a local folder on your machine to map the Proguard file to the specific build:
85-
- The file should contain the following (change the versionCode and versionName to match your build):
107+
- "Create Release" and upload the signed APK, set the version to match the github tag (for example: `3.3.0` with version code matching the Bitrise build number) then "Review" and the build will be immediately available to the core team
108+
2. Map the `app-mapping-YOURBUILDNUMBER.txt` to the specific build for Proguard
109+
- Create an xml file named `AndroidManifest-YOURBUILDNUMBER.xml` in a local folder on your machine
110+
- The file should contain the following (change the versionCode and versionName to match your numbers from `app/build.gradle`):
86111
```
87112
<?xml version="1.0" encoding="utf-8"?>
88113
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
89114
package="mozilla.lockbox"
90115
android:versionCode="4053"
91-
android:versionName="1.1.1" >
116+
android:versionName="3.3.0" >
92117
</manifest>
93118
```
94-
- this file will be used in step 8
95-
7. [Create an auth token](https://sentry.prod.mozaws.net/settings/account/api/auth-tokens/) for your sentry account that will allow you to create releases. This will be used when uploading the `app-mapping` and `AndroidManifest`.
119+
3. Next, [create an auth token](https://sentry.prod.mozaws.net/settings/account/api/auth-tokens/) for your sentry account that will allow you to create releases. This will be used when uploading the `app-mapping.txt` and `AndroidManifest.xml`.
96120
- **Note:** if you have already created an auth token, there is no need to create a new one.
97-
8. In Sentry, browse to "Android Vitals" and "Deobfusication files" and upload the `app-mapping.txt` file from step 6
98-
- Upload the mapping and manifest to Sentry using `sentry-cli` and following [these instructions](https://docs.sentry.io/cli/dif/proguard/)
121+
4. Upload the mapping and manifest to Sentry using `sentry-cli` and follow [these instructions](https://docs.sentry.io/cli/dif/proguard/)
99122
- The upload script should look something like this:
100123
```
101124
SENTRY_URL=https://sentry.prod.mozaws.net/ sentry-cli --auth-token YOURSENTRYAUTHTOKEN upload-proguard --android-manifest /PATH/to/manifest/AndroidManifest-YOURBUILDNUMBER.xml --org operations --project lockwise-android /PATH/to/appmapping/app-mapping-YOURBUILDNUMBER.txt --no-reprocessing
102125
```
103126
- HINT: if you get a 411 "content-length" error, you may need to add the `--no-reprocessing` flag due to a bug with GCP and the `sentry-cli`
104-
105-
### Distributing Builds through Play Store (Internal, Alpha)
106-
107-
_All builds must be manually uploaded from bitrise to Play Store Console as an artifact aka "New Release" in the "Preparing" instructions above. Only mobile engineering managers and Release Management team members (See #release-coordination) have access to create new non-production releases._
108-
109-
1. Browse to [App Releases][2] in Play Console
110-
2. Browse to the "Internal test track" (this release should already be uploaded and available to the core Lockwise team)
111-
3. Promote the release to the (internal, still) Alpha channel using the "Promote to Alpha" button, complete the questions
127+
5. From the Play Console, browse to “Android vitals” and “Deobfuscation files”
128+
- Upload the `app-mapping.txt` for the new release
129+
6. Once the internal build is uploaded and tested, upgrade the release from the Play Console “App releases” page to alpha and beta as needed.
112130
113131
### Distributing through the Play Store (Production)
114132
115-
_Only Release Management team members (see private #release-coordination channel in Mozilla Slack) have access to distribute production releases through the Play Store._
133+
_Only Release Management team members have access to distribute production releases through the Play Store. A bug must be filed in Bugzilla in order to promote a release to production._
116134
117135
1. Contact release management by filing a bug under **[Release Engineering: Release Requests](https://bugzilla.mozilla.org/enter_bug.cgi?product=Release%20Engineering&component=Release%20Requests)**
118136
2. Note the expected version, build and which channel it is in (internal? Alpha? Beta?). [For example](https://bugzilla.mozilla.org/show_bug.cgi?id=1555746):
@@ -121,23 +139,15 @@ _Only Release Management team members (see private #release-coordination channel
121139
122140
NOTE: _brand new_ apps may take 1 or more hours to appear in the Play Store whereas existing app (updates) can appear within minutes. Schedule accordingly!
123141
124-
## In Case of Emergency (Release)
125-
126-
_similar to above, but requires explicit cherry-pick commits on `production` branch when `master` branch is not in a release-able state_
127-
128-
1. Merge the emergency changes or fixes or features to default `master` branch as usual
129-
2. Update the release notes
130-
3. Create and merge a pull request _up to and including_ the last release-able commit on `master` to `production`
131-
4. Then `git cherry-pick` each additional commit from `master` to be included in the release
132-
- thus skipping or avoiding the non-release-able commits
133-
5. Push the resulting `production` branch to GitHub.com
134-
6. Create a tag from `production` matching the format: `major.minor.patch.build`
135-
- for example: `git tag -a -s 1.3.1.1624 -m "1.3.1 (Build 1624)"`
136-
7. Push the tag to GitHub and create a corresponding "Release" on github
137-
- copy the release notes from `release-notes.md` to the Github release
138-
8. Browse to bitrise and find the desired `production` branch build to distribute
139-
9. Follow the same instructions above starting at _Step 5_.
140-
10. Continue the "Distributing..." instructions
141142
142143
[1]: https://app.bitrise.io/app/20089a88380dd14d
143144
[2]: https://play.google.com/apps/publish/?account=7083182635971239206#ManageReleasesPlace:p=mozilla.lockbox&appid=4972100280256015711
145+
[3]: https://github.com/mozilla-lockwise/lockwise-android/compare
146+
[4]: https://devcenter.bitrise.io/builds/Starting-builds-manually/
147+
[5]: https://github.com/mozilla-lockwise/lockwise-android/milestones
148+
[6]: https://jira.mozilla.com/browse/PI-384
149+
[7]: https://app.bitrise.io/build/0badfa6c6476aa75#?tab=log
150+
[8]: https://github.com/mozilla-lockwise/lockwise-android/compare/master...release-v3.x
151+
[9]: https://github.com/mozilla-lockwise/lockwise-android/releases
152+
[10]: https://github.com/mozilla-lockwise/lockwise-android/releases/new
153+
[11]: https://sentry.prod.mozaws.net/operations/lockwise-android/

0 commit comments

Comments
 (0)