Prepare a release

There exist two kinds of releases: bugfix releases, with no new features, and plain releases, with new features, refactorings, etc.

Maintaining the changelog between releases

As soon as a full release got released, all further changes on the release branch (classic bugfixes) (which is always merged into the master branch) need to be documented in the /main/res/raw/changelog_bugfix.md on the release branch only.

Changes which are done on the master branch only (e.g. new features) need to be documented in the changelog_base.md on the master branch only.

For details see https://github.com/cgeo/cgeo/wiki/Changelog-handling

The only exception from this way of documenting the changes is needed when a new feature release is prepared. This is described in the next chapter.

Preparing for a feature release

In fact, all releases are cut from the release branch. When we want to do a feature-full release, we apply the following steps:

• empty changelog_bugfix.md on branch master (and insert a single newline (CRLF) to ensure Crowdin emptying translations on next delivery)

• fast-forward release branch to the head of master branch: (Note that since release is always merged back into master, we have a guarantee that merging master into release will result into a fast-forward operation.)

  $ git checkout release
  $ git merge --ff-only origin/master
  

• then insert the correct version number into /main/src/cgeo/geocaching/utils/BranchDetectionHelper.java on branch release only (will be merged back to master later on)

• no need for manually comparing changelog files any more, and titles like next feature release etc. are added automatically by c:geo - you only need the version number for a full release

• Late changes before releasing have to be added to changelog_master.md on release to be included

• As soon as the release is out (meaning: the final release, not a RC) changelog_master.md on master can be emptied to be ready for the next cycle

Release procedure

Before doing a release, we have to ensure that:

• the developers are ok with it, as they may be aware of some lingering issues that don't show during the tests but may become problematic on the field;
• the Q&A team is ok with it, as they may have started to document oddities or critical bugs that developers are not yet aware of;
• the tests are all green.

Once those conditions are met, various steps need to be done:

Update translations, changelog and version

1. The release notes must be updated by the Q&A team, from the output of git shortlog --no-merges previoustag..release where previoustag is the tag of the latest released version.
   • for a full release, the changelog is stored in /main/res/raw/changelog_base.md on branch release
   • for every following bugfix release, the changelog is stored in /main/res/raw/changelog_bugfix.md on branch release (and the changelog_base.md is kept unchanged)
   • for a detailed info on changelog handling see our Wiki page on Changelog handling
2. Update the version number
   • for a full release, the version number is stored in /main/src/cgeo/geocaching/utils/BranchDetectionHelper.java on branch release
   • for every following bugfix release, the version number is stored in /main/res/raw/changelog_bugfix.md on branch release (and the version number of the feature release is is kept unchanged)
3. [Optional] If there have been recent changes in any of the involved changelog files: Wait for crowdin to catch up, as existing translations may have been invalidated by crowdin due to changes in their positions.
4. [Optional] Import translations from crowdin using the scripts in the crowdin top-level directory. From the main directory, run ../crowdin/download release and merge the crowdin_translations branch. - for a bugfix release this is a "must-have" step to get the version number into the translated versions of changelog_bugfix.md
5. [optional] A RC build may be started and distributed to beta testers. Return to step 1 or 2 after this phase.
6. Tag the code used for the release version with a name like market_20130605. This corresponds to release whose version name is 2013.06.05 and version code is 20130605.

Build and upload

1. Start a release build on Jenkins. The versionCode and versionName will be set appropriately. The APK will be uploaded to our webserver automatically.
2. Manually check the release APK, and in particular the upgrade path from the old to the new version.
3. Upload the APK to the Google Play developer console and update the changes section, limited to 500 characters.
4. Enable the APK in the Google Play developer console. This will push the update to our users. For releases with a lot of new functionality, you may want to use staged rollouts, e.g. to make the new release only available to 10% of the users on the first day, 25% on the second day and so on. This can reduce the pressure, if new issues occur with that release.

Update status page and website

1. When the new version seems to be available from the Google Play store (i.e. people can upgrade via Play Store), enable it on the status page.

Trigger Publish to F-Droid repository

The mainline F-Droid repository, need to be triggered to publish the latest release.

1. Start the publishing job on CI.

Update Github releases and milestones

1. Create a new release on https://github.com/cgeo/cgeo/releases. Use the tag from above and upload the new APK file. This is important as we use the link https://github.com/cgeo/cgeo/releases/latest in our app, and this automatically points to the latest uploaded APK.

Special for legacy release

We made the following agreement (for the time being) for legacy releases:

android:versionCode should just be increased by 1 (to make sure the version code is lower than the non-legacy release version)

android:versionName should contain the date of the release and the addition -legacy (e.g. 2014.06.12-legacy)

Setting android:versionCode and android:versionName is done on the CI server as parameters for the build job. The data in AndroidManifest.xml is overwritten while building on CI.