Client Release Procedure

This page describes how to manage an Android Client release. If you're managing a release, you must be a GitHub owner. You should also be very familiar with our development environment; if not, you might want to start here.

Prerequisites

First make sure you have the git flow extension installed. On a Mac, brew install git-flow, or on Linux, apt-get install git-flow.

Then make sure git flow is initialized in your working directory, with the master and dev branches pulled from the origin repository:

  git checkout -b master origin/master
  git checkout -b dev origin/dev
  git flow init

You'll be asked a few questions. You only need to type "dev" for next release development and "v" for the version tag prefix. Hit Enter to get the default for everything else:

  Branch name for production releases: [master]
  Branch name for "next release" development: [master] dev   # <-- type "dev"
  How to name your supporting branch prefixes?
  Feature branches? [feature/]
  Release branches? [release/]
  Hotfix branches? [hotfix/]
  Support branches? [support/]
  Version tag prefix? [] v  # <-- type "v"

Starting a release branch

When it's time to freeze new feature development, start a release branch for work focused on stability and bugfixes:

  git checkout dev  # Switch to the dev branch
  git pull  # Sync local dev with origin/dev
  git flow release start N.N.N  # Start a release
  git flow release publish N.N.N  # Make the release available to others

Replace N.N.N with the release number. Release numbers generally consist of two or three numbers, joined with periods (digits only, no letters).

At this point, new feature development can continue on the dev branch, and the release branch can have a "bugfixes only" policy. Try to wait until the codebase is feature-complete before opening a release branch; doing lots of development on a release branch results in lots of work to merge those changes back into dev later.

Declaring the release

When you are sufficiently satisfied with the stability and quality of the tip of the release branch, it's time to declare the release, which consists of merging to both master and dev and tagging a commit. This command does all of that:

  git fetch
  git flow release finish N.N.N

If there have been no changes on dev since the last release, git flow will put the tag on the wrong commit (it tags dev rather than master). In that case, you must do git tag -f vN.N.N master to move the tag to the correct place.

This will merge the release branch to both master and dev and tag the commit on master.

You'll be asked to enter two commit messages in order: First, a merge message; secondly, a tag description. For both of these, enter the release message you composed.

Finally, use these commands to publish the new release on GitHub:

  git push --tags origin master
  git push origin dev            # ensure that any changes backported to dev get pushed

CircleCI will detect that a new tag has been applied to the master branch, and kick off the construction of newly versioned packages, and then include them in the project apt repository.

The new release will appear in the list of releases on GitHub.

TODO: Confirm this?

Building the release APK

Your push to master (the git push command above) will be automatically detected by CircleCI. The APK file should be available in the artifacts tab under the CircleCI build.

TODO: publish the release APK somewhere that it can be consumed?

Jenkins will then build the client-master job and publish the resulting .apk file at both http://packages.projectbuendia.org:9001/ and http://builds.projectbuendia.org/, all using the version number you specified in the tag. http://packages.projectbuendia.org:9001/ is a machine-friendly package repository that the app checks in order to automatically download updates, whereas http://builds.projectbuendia.org/ is a human-friendly download page for the app. This APK will not be signed.

If you left out the --tags option when pushing to master, the Jenkins job will fail. No need to worry; just do the proper git push --tags origin master and then manually kick off the client-master job in the Jenkins web UI (click "Build Now").

Creating a signed release APK (optional, not required)

This step is optional and that release repo doesn't exist so someone needs to figure out how to do this and document it here. Skip this for now

To create a signed release APK, you'll first need access to our signing key. Clone the release repository into a sibling directory of your client repository:

  cd ..
  git clone [email protected]:projectbuendia/release.git

Then build the release binary from command line:

  cd client
  git checkout vN.N.N
  ./gradlew clean
  ./gradlew :app:assembleRelease

You will be prompted Please enter key passphrase:. Only project owners have access to this passphrase.

When the build finishes, it will create a release binary at app/build/outputs/apk/app-release.apk.