Skip to content

Release procedure

Jump to bottom Edit New page
Mike Hardy edited this page Sep 7, 2020 · 25 revisions

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. Alphas a released from master during this phase.

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, commits will be added to that "release-N.n" branch and releases will be made from it.

Alpha or beta release procedure

  • Always use this repository: https://github.com/ankidroid/Anki-Android
  • Checkout the branch to release ("master" for an alpha, or for instance "release-2.9" for a beta)
  • In AndroidManifest.xml change android:versionName from 2.9beta11 to 2.9beta12 (for instance), and change android:versionCode accordingly.
    • As a special case, when creating a new patch release (e.g., v2.9.4, you will start by calling your first beta 2.9.4beta0 with release version code ending 00 - the release script will bump those 0's to 1's for the first beta of the new patch release)
  • The tools/release.sh script will bump the versions, compile and upload to Google Play + Github and tag and push
    • The tool will ask for a keystore and key password, the release keystore and the passwords are private information for release managers only. Similarly, you will need credentials to the Play Store and the Amazon App Store in order to finalize the public releases
    • The release script makes use of the github-release tool, gawk, sed, and asciidoctor - it will verify they are present and error if they are not
    • As a special case, when creating a new release branch, will have to set the branch (git push --set-upstream origin release-2.11 for example) and then run git push --tags to get the new branch contents correct in github

Stable release procedure

Build

  • Update the changelog in the ankidroiddocs repository and/or the manual with notable changes - the tools/release.sh script will help you by enforcing this
  • Always use this repository: https://github.com/ankidroid/Anki-Android
  • Consider syncing translations from crowdin if they are still backwards compatible (no strings were deleted) - do this on master and cherry-pick -x commit-hash to the release branch
  • Switch to the branch to release, for instance "release-2.10"
  • Run ./tools/release.sh public to compile/upload/tag and push to github, Play Console, and Amazon App Store
  • After the release script is finished, the stable build will be in the beta channel. Manually promote it to production using the web interface of the Play Console

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.

Merging new changes from master into a release or hotfix branch

Check out the release branch and using git on the command line cherry-pick -x commit-hash the commits from master that you want

The following instructions have been left for posterity, but are not currently used:

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

Amazon App Store

This is a partially manual process, but Amazon has begun accepting our builds again

You need to be part of Nicolas Raoul's Amazon Developer organization (he can send you an invite, currently Mike Hardy is a member) and with that you authority you may create new releases and submit them for review / distribution. You will also need the Amazon App Store publishing credential JSON (similar to the Google Publishing JSON needed for the Play Store)

After running the release script, for public releases only, there should be a new release present on the Amazon App Store in unpublished state: https://developer.amazon.com/apps-and-games/console/apps/list.html - fill in the description for the release, and submit it for review

GitHub Automated Workflow

There is a new way to publish, using GitHub Actions

Crowdin / translations sync

  1. Run the Sync Translations Action
  • open that action
  • find the button on the right labeled "Run Workflow"
  • Run the workflow against the master branch
  1. Make a PR for the resulting changes - https://github.com/ankidroid/Anki-Android/compare/i18n_sync?expand=1
  2. Have someone review and approve the PR and merge it to master

Cutting a new release branch

  1. Checkout the main branch and verify everything is working with a ./gradlew clean jacocoTestReport
  2. Make the branch, for example if you want release-2.14 you do a git co -b release-2.14
  3. Edit AnkiDroid/build.gradle to switch the version from alphaNN to beta0, like this (the release script will handle taking it from 0 to 1 on the first run)
  4. Push the changes (for example if you are making release-2.14 - git push --set-upstream origin release-2.13)
  5. Now follow the "Publishing new versions" section here, but select the new branch you just pushed

Publishing new versions

Note: This is for alpha only right now. It will be extended for the betas as a next step

  1. Run the Publish Action
  • Open that action
  • Find the button on the right labeled "Run Workflow"
  • Run the workflow against the master branch for alphas, or the correct release branch for betas/public releases
  1. For public releases
  • make sure changelog.asc in ankidroiddocs has an entry for the new version on it's master branch or the release script will abort
  • go to the various stores (Google Play Store, Amazon App Store, Huawei AppGallery) and submit the new build for release

Help us make AnkiDroid better: Sponsor AnkiDroid on GitHub Sponsors 💜

Add a custom sidebar
Clone this wiki locally