Release procedure

This page describes how to release AnkiDroid. It can be interesting as an insight to understand the project better, or to improve the procedure.

Development lifecycle

There are three main phases the project alternates between (alpha, beta, stable).

We use a simple branching model where "master" (the default branch) contains the latest (unstable) development code, which is where all merge requests should be submitted. When we move into the "beta" phase of the development cycle, we implement a feature freeze, and a temporary branch "release-N.n" (N.n being the version code) is created which is only for important bug fixes. During this period, important bug fixes are merged by the development team into "release-N.n" (see below). If an urgent bug is discovered shortly after a major release, a special "hotfix-N.n" branch will be created from the tag from the latest source code.

Alpha or beta release procedure

• Always use this repository: https://github.com/ankidroid/Anki-Android
• Checkout the branch to release ("develop" for an alpha, or for instance "release-0.6" for a beta)
• In AndroidManifest.xml change android:versionName from 0.6beta11 to 0.6beta12 (for instance), and change android:versionCode accordingly.
• Build an APK using ./gradlew assembleRelease or Android Studio
• Upload the APK to github
• Upload the APK to Google Play alpha or beta
• Commit and push The tools/release.sh script can perform some of those steps effortlessly.

Stable release procedure

Build

• Always use this repository: https://github.com/ankidroid/Anki-Android
• Switch to the branch to release, for instance "release-0.6"
• Change icons to blue by reverting the first icon commit of this version ( tools/change-icons-to-blue.sh )
• In AndroidManifest.xml change android:versionName from 0.6beta13 to 0.6 (for instance) and change android:versionCode accordingly.
• Commit, push.
• Tag the version: git tag v0.6
• Push: git push --tags
• Build a signed APK using ./gradlew clean assembleRelease. Rename it from bin/AnkiDroid-release.apk to AnkiDroid-0.6.apk for instance
• Go to https://github.com/ankidroid/Anki-Android/tags click "Edit release notes" drop APK over drop zone, press "Update release". Running ./tools/release.sh public can perform some of those steps effortlessly.

Google Play

Upload the APK to Google Play. Archive the previous APK from the "Active" section, then publish.

Title and Description for each language:

• Title: docs/marketing/localized description/android-titles.txt
• Description: docs/marketing/localized description
• New feature list: Run tools/humanize-new-features.sh

Send an email to the mailing list announcing the new version, link to APK, new features, localizations, and thanking the developers, translators, testers.

Chrome Web Store

This makes the new build available to Chromebook users that do not have access to the Play Store. You must be a member of the google group "AnkiDroid Web Store Publishers".

• Download the release (e.g., "AnkiDroid-2.8.4.apk") from the Releases page
• Grab the APK to CRX conversion script
• Use the release script in the chromeos tools directory to transform the APK to the CRX file needed for ChromeOS
  • ./release.sh <FULL PATH TO THE APK-TO-CRX SCRIPT>/apk_to_crx.py <FULL PATH TO THE APK>/AnkiDroid-2.8.4.apk
• Go to the Chrome Web Store developer dashboard
• Upload the new crx file and publish it, with any notes that seem necessary

Merging new changes from master into a release or hotfix branch

The following procedure can be used to go through all of the new commits in the master branch, and choose one by one whether or not to merge them into a release branch. Commit messages including the tag @branch-specific (such as version bump commits generated by the release script) can be skipped automatically.

# One time setup.
git clone [email protected]:ankidroid/Anki-Android.git
cd Anki-Android

# Every time setup.
RELEASE_BRANCH=release-2.9  # Update this accordingly.
git fetch
git checkout master
git pull origin master --ff-only
git checkout $RELEASE_BRANCH
git pull origin $RELEASE_BRANCH --ff-only

# Pick one of the following to options:

# 1. Manual flow
./tools/gitflow-integrate  show master $RELEASE_BRANCH
# This will tell you what the tool will do by default, merge or skip.

# Decide which action to take:
# a. Default action (shown above).
./tools/gitflow-integrate apply master $RELEASE_BRANCH
# b. Force a merge.
./tools/gitflow-integrate  merge master $RELEASE_BRANCH
# c. Force a skip.
./tools/gitflow-integrate  skip master $RELEASE_BRANCH
# Skips should be applied to version number changes,
# release packaging changes (i.e., change to icons, commenting
# of logs, etc.), and cherry-picks from develop into a release
# branch.
#
# Repeat until nothing is left to merge.

# 2. Automated flow
while ./tools/gitflow-integrate apply master $RELEASE_BRANCH; do
   echo;
done
# Note that this will always just do the default action for every commit.
# If @branch-specific is set in all the right places (see above for the
# common types of commit that should be skipped) then things should
# just work.

# NOTE: If a merge conflict arises, you will get a message like:
#   Automatic merge failed; fix conflicts and then commit the result.
#   Please resolve conflict and press ENTER
# You should resolve the conflict and press ENTER to continue.
# Remember to add 
# Make sure things still build.
./gradlew clean assembleDebug

# Show / confirm the list of changes
git log --first-parent origin/$RELEASE_BRANCH..$RELEASE_BRANCH --format='%B' --reverse

# Push changes 
git push