Fennec Migration

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

📱 Testing

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

The following links point to the latest Fenix (Firefox Preview) builds (Nightly; from master) that are setup to replace a Fennec (Firefox for Android) release version (org.mozilla.firefox).

• ARM64/Aarch64 devices (64 bit; Android 5+)
• ARM devices (32 bit; Android 5+)
• x86_64 devices (64 bit; Android 5+)
• x86 devices (32 bit; Android 5+)

❌ At this point in time you are going to lose data when replacing Fennec (Firefox for Android) with Fenix (Firefox Preview)!

📝 Changelog

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

• 2019-09-18 - The first migration builds are available now. A Firefox 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.

💻 Development

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

Fennec

Checkout the ESR68 branch and setup a regular Fennec build by following mach bootstrap. An "artifact mode" build should be sufficient for most migration work.

Not build and install Fennec (mach build, mach package, mach install).

By default the build from this branch may be looking for an adjust token that does not exist. To get past this problem just create a dummy token and let the build read it:

echo "trackme" > adjust.token
echo "ac_add_options --with-adjust-sdk-keyfile=`pwd`/adjust.token" >> mozconfig

For setting up Fenix you will need to know the application ID and sharedUserId of your Fennec build. Like the app name (when the app is installed) those will use the username of your build machine:

application id = org.mozilla.fennec_$USERNAME
sharedUserId = org.mozilla.fennec_$USERNAME.sharedID

If you are unsure about the values then you can grab the APK from MOZ_OBJDIR/dist/ and inspect its manifest contents in Android Studio.

Fenix

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

Now you'll need to setup your build to use the same application id and sharedUserId as your Fennec build (see above) as well as turn the build into a debug build.

In app/build.gradle (Not the root build.gradle file!) look for the fennecProduction build type and modify it to use your values.

• Replace "applicationIdSuffix" and "sharedUserId"
• Remove the "releaseTemplate" inheritance

        fennecProduction { // Remove the "releaseTemplate" inheritance here!
            // [..]
            // Replace $USERNAME with the value from your Fennec build
            applicationIdSuffix ".fennec_$USERNAME"
            debuggable true // Make this build debuggable!
            matchingFallbacks = ['debug'] // Use "debug" fallback for other dependencies.
            signingConfig signingConfigs.debug // Use the debug signing config
            manifestPlaceholders = [
                // Replace $USERNAME with the value from your Fennec build
                "sharedUserId": "org.mozilla.fennec_$USERNAME.sharedID"
            ]
        }

Note that you only need to setup the suffix of the application id (Omit org.mozilla).

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

Sample browser

When working on migration code that lives in the Android Components repository it can be helpful to replace a local Fennec 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.fennec_$USERNAME.sharedID"
    [..]

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

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

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

Emulator snapshots

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

• (1) Uninstall an already existing Fennec/Fenix installation
• (2) Install Fennec
• (3) Use Fennec 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 Fennec 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.