IceCatMobile Migration

Project board: https://github.com/orgs/mozilla-mobile/projects/40

📱 Testing

⚠️ Warning: Replacing a IceCatMobile (IceCat for Android) installation with Fenix (IceCat Preview) can (and at the time of writing this definitely will) result in DATA LOSS. Do not replace an installation of IceCatMobile (IceCat for Android) that contains data you do not want to risk losing (e.g. open tabs, history, bookmarks, top sites, ..).

Release

The following links point to the latest Fenix (IceCat Preview) builds (Nightly; from main) that are setup to replace a IceCatMobile (IceCat for Android) release version (org.gnu.icecat).

Beta

The following links point to the latest Fenix (IceCat Preview) builds (Nightly; from main) that are setup to replace a IceCatMobile Beta (IceCat for Android - Beta) release version (org.gnu.icecat.beta).

Nightly

The following links point to the latest Fenix (IceCat Preview) builds (Nightly; from main) that are setup to replace a IceCatMobile Nightly (IceCat for Android - Nightly) release version (org.mozilla.icecatmobile_aurora).

📝 Changelog

The data migration work is tracked on the following project board: https://github.com/orgs/mozilla-mobile/projects/40

2019-09-05 - The first migration builds are available now. A IceCat for Android (release) installation can be replaced with them. No actual migration code is in those builds yet. The replaced build is a "clean" Fenix installation.
2019-10-22 - First iteration of migration code to migrate history, bookmarks and open tabs landed in builds.
2019-11-02 - IceCat Account users remain logged in after migrating to Fenix.

💻 Development

When working on migration code it is helpful to have a local IceCatMobile build and a local Fenix build that can replace the IceCatMobile build. The following manual setup is needed to achieve that.

In the example commands below, we assume you are replacing a IceCatMobile Nightly build with a Fenix Nightly build.

IceCatMobile

Download the latest version of IceCatMobile:

Strip out the original signature:

zip --delete icecatmobile.apk "META-INF/*"

Re-sign the APK with your own debug key (that will also be used later for Fenix):

jarsigner -verbose -keystore ~/.android/debug.keystore -storepass android -keypass android icecatmobile.apk androiddebugkey

You can now install this APk that is ready to be used for migration:

adb install icecatmobile.apk

Fenix

In the app/build.gradle, add the following line in the correct scope to sign your app with the same debug key used on the IceCatMobile APK:

android {
  buildTypes {
    icecatmobileNightly {
      signingConfig signingConfigs.debug
    }
  }
}

Follow the build instructions in the README to get a Fenix build setup.

Now select the geckoNightlyIceCatMobileNightly build variant in Android Studio and deploy it. This build should have replaced your IceCatMobile build now.

Sample browser

When working on migration code that lives in the Android Components repository it can be helpful to replace a local IceCatMobile build with the sample browser (instead of Fenix). The following setup is needed for that.

Add the sharedUserId to the AndroidManifest.xml of sample browser:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:sharedUserId="org.mozilla.icecatmobile_$USERNAME.sharedID"
    [..]

Modify the application id in build.gradle of the samples-browser module and use a versionCode that is higher than your IceCatMobile build (2100000000 is the highest allowed version code and therefore should always work).

    defaultConfig {
        applicationId "org.mozilla.icecatmobile_$USERNAME"
        [..]
        versionCode 2100000000

Click on "Sync Project with Gradle Files" and deploy the sample browser. This build should have replaced your IceCatMobile build now.

Emulator snapshots

When testing migration code the following process has to be repeated multiple times:

(1) Uninstall an already existing IceCatMobile/Fenix installation
(2) Install IceCatMobile
(3) Use IceCatMobile to create the necessary data for testing the migration
(4) Install Fenix
(5) Debug / Test

Steps (1) to (3) can be quite time consuming. Emulator snapshots can help with that:

Launch an emulator and perform steps 1 to 3. You may need to modify your IceCatMobile build to create an X86 build for your emulator (target i686-linux-android).
Click on the three dot menu in the emulator toolbar and select "Snapshots". Press the "Take Snapshot" button. If needed give you snapshot a descriptive name in case you will need to have multiple "test snapshots".
With the "Play" button you can always reset your emulator to that state and repeat the migration process.

7.9 KiB Raw Blame History