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

Commit 2218ebd

Browse files
author
Elise Richards
committed
Update release docs
1 parent 536b0de commit 2218ebd

1 file changed

Lines changed: 83 additions & 59 deletions

File tree

‎docs/releases.md‎

Lines changed: 83 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -27,73 +27,90 @@ _all commits on all branches and pull requests are automatically built_
2727

2828
## Preparing a Release (for Internal, Alpha, or Production via Play Store)
2929

30+
### Collect necessary identifiers for the new build
31+
32+
Before you can begin a new production release, it is necessary to take the following steps into consideration:
33+
34+
1. Find the current production version number. Using the strategy below, increment the version number to identify the state of the new release.
35+
- **Choosing a new release version number**
36+
- 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.
37+
- For normally scheduled releases, the left-most value is incremented and the following two numbers "reset" to zero.
38+
- Example: after release `2.1.0`, the next normally scheduled release would be version `3.0.0`.
39+
- 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.
40+
- 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.
42+
- 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+
52+
### Create a release branch and prepare the production branch
53+
3054
1. Update the release notes under `docs/release-notes.md`
31-
- create a pull request to collaborate and get approval
32-
- determine the next build number and include it in release notes
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
3357
- merge the release notes to `master` branch
3458
- this will result in a release build matching the build number provided
35-
2. Create and merge a pull request _from_ `master` _to_ `production` so it tracks the release
36-
- https://github.com/mozilla-lockwise/lockwise-android/compare/production...master
37-
3. Create a tag from `production` matching the format: `major.minor.patch.build`
38-
- for example: `1.2.1399` is major version 1.2, bitrise build 1399
39-
- for example: `1.3.1.1624` is major version 1.3 with 1 patch release, (bitrise) build 1624
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`
64+
65+
### Create the Play Store release
66+
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
4071
- `git tag -a -s 1.3.1.1624 -m "1.3.1 (Build 1624)"`
41-
4. push the tag to GitHub and create a corresponding "Release" on GitHub.com
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
4274
- mark this as a "pre-release" until PI requests are finished
4375
- copy the release notes to the "Release" on GitHub
44-
- download the `-signed.apk` from bitrise and attach it to the Release on GitHub
45-
- **open the `-signed.apk` and confirm release build does not allow screenshots and does not expose the contents of the app in the switcher**
46-
5. Upload the `-signed.apk` (from bitrise) to the [Play Console][2]:
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]:
4779
- browse to "Release Management" > "App Releases" > "Internal test track" > "Manage"
48-
- "Create Release" and upload the signed APK, set the version to match the tag (for example: `1.2.1339`) then "Review" and the build will be immediately available to the core team
49-
6. Download the `app-mapping.txt` (ProGuard rules) from bitrise and create an `AndroidManifest.xml` (in a local folder on your machine) to map the file to the specific build:
50-
```
51-
<?xml version="1.0" encoding="utf-8"?>
52-
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
53-
package="mozilla.lockbox"
54-
android:versionCode="4053"
55-
android:versionName="1.1.1" >
56-
</manifest>
57-
```
58-
- Suggestion: rename the file to `AndroidManifest-BUILDNUMBER.xml` to make it less generic
59-
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`. If you have already created an auth token, there is no need to create a new one.
60-
8. Browse to "Android Vitals" and "Deobfusication files" and upload the `app-mapping.txt` file from bitrise.io
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
6182
- Suggestion: rename the file to `app-mapping-BUILDNUMBER.txt` to make it less generic
62-
9. Upload the mapping and manifest to Sentry using `sentry-cli` and following [these instructions](https://docs.sentry.io/cli/dif/proguard/)
63-
- The upload script should look something like this:
64-
```
65-
SENTRY_URL=https://MYSENTRYURL/ sentry-cli --auth-token MYAUTHTOKEN upload-proguard --android-manifest /PATH/to/manifest/AndroidManifest-4854.xml --org operations --project lockwise-android /PATH/to/appmapping/app-mapping-4854.txt
66-
```
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):
86+
```
87+
<?xml version="1.0" encoding="utf-8"?>
88+
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
89+
package="mozilla.lockbox"
90+
android:versionCode="4053"
91+
android:versionName="1.1.1" >
92+
</manifest>
93+
```
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`.
96+
- **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/)
99+
- The upload script should look something like this:
100+
```
101+
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
102+
```
67103
- 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`
68-
10. Continue the "Distributing..." instructions
69104
70-
### In Case of Emergency (Release)
71-
72-
_similar to above, but requires explicit cherry-pick commits on `production` branch when `master` branch is not in a release-able state_
73-
74-
1. Merge the emergency changes or fixes or features to default `master` branch as usual
75-
2. Update the release notes
76-
3. Create and merge a pull request _up to and including_ the last release-able commit on `master` to `production`
77-
4. Then `git cherry-pick` each additional commit from `master` to be included in the release
78-
- thus skipping or avoiding the non-release-able commits
79-
5. Push the resulting `production` branch to GitHub.com
80-
6. Create a tag from `production` matching the format: `major.minor.patch.build`
81-
- for example: `git tag -a -s 1.3.1.1624 -m "1.3.1 (Build 1624)"`
82-
7. Push the tag to GitHub and create a corresponding "Release" on GitHub.com
83-
- copy the release notes to the "Release" on GitHub
84-
8. Browse to bitrise and find the desired `production` branch build to distribute
85-
9. Follow the same instructions above starting at _Step 5_.
86-
10. Continue the "Distributing..." instructions
87-
88-
## Distributing Builds through Play Store (Internal, Alpha)
105+
### Distributing Builds through Play Store (Internal, Alpha)
89106
90107
_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._
91108
92109
1. Browse to [App Releases][2] in Play Console
93110
2. Browse to the "Internal test track" (this release should already be uploaded and available to the core Lockwise team)
94111
3. Promote the release to the (internal, still) Alpha channel using the "Promote to Alpha" button, complete the questions
95112
96-
## Distributing through the Play Store (Production)
113+
### Distributing through the Play Store (Production)
97114
98115
_Only Release Management team members (see private #release-coordination channel in Mozilla Slack) have access to distribute production releases through the Play Store._
99116
@@ -104,16 +121,23 @@ _Only Release Management team members (see private #release-coordination channel
104121
105122
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!
106123
107-
## Preparation before and after a release
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_
108127
109-
- **Before testing or distributing a release**: make sure the release number is still what you want and expect it to be, especially if major (versus minor) changes were made. (see below on how to _"change the version"_).
110-
- **Before public release**: make sure no open "localization strings" Pull Requests are open
111-
- **After public release**: consider filing an issue for the next sprint/release to update to the latest dependencies (application-services, for example)
112-
- **After public release**: consider running `mkdocs gh-deploy` so the latest `docs` are also published to the GitHub pages website
113-
- **After public release**: _change the version_ to a major or minor update depending on the future plans.
114-
- Update the `versionName` value (and `versionCode` if applicable) in `app/build.gradle`
115-
- Also update the value in the `list_cell_setting_appversion.xml` layout to _the exact same version_
116-
- **After public release**: 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.
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
117141
118142
[1]: https://app.bitrise.io/app/20089a88380dd14d
119143
[2]: https://play.google.com/apps/publish/?account=7083182635971239206#ManageReleasesPlace:p=mozilla.lockbox&appid=4972100280256015711

0 commit comments

Comments
 (0)