mobile/android/fenix/docs/Fennec-Migration.md

   1 # Fennec Migration
   2
   3 Project board: https://github.com/orgs/mozilla-mobile/projects/40
   4
   5 ## 📱 Testing
   6
   7 ⚠️ **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, ..).
   8
   9 ## Release
  10
  11 The following links point to the latest *Fenix* (Firefox Preview) builds (Nightly; from `main`) that are setup to **replace** a *Fennec* (Firefox for Android) release version (`org.mozilla.firefox`).
  12
  13 * [ARM64/Aarch64 devices (64 bit; Android 5+)](https://firefox-ci-tc.services.mozilla.com/api/index/v1/task/project.mobile.fenix.v2.fennec-production.latest/artifacts/public/build/arm64-v8a/geckoBeta/target.apk)
  14 * [ARM devices (32 bit; Android 5+)](https://firefox-ci-tc.services.mozilla.com/api/index/v1/task/project.mobile.fenix.v2.fennec-production.latest/artifacts/public/build/armeabi-v7a/geckoBeta/target.apk)
  15 * [x86_64 devices (64 bit; Android 5+)](https://firefox-ci-tc.services.mozilla.com/api/index/v1/task/project.mobile.fenix.v2.fennec-production.latest/artifacts/public/build/x86_64/geckoBeta/target.apk)
  16 * [x86 devices (32 bit; Android 5+)](https://firefox-ci-tc.services.mozilla.com/api/index/v1/task/project.mobile.fenix.v2.fennec-production.latest/artifacts/public/build/x86/geckoBeta/target.apk)
  17
  18 ## Beta
  19
  20 The following links point to the latest *Fenix* (Firefox Preview) builds (Nightly; from `main`) that are setup to **replace** a *Fennec Beta* (Firefox for Android - Beta) release version (`org.mozilla.firefox.beta`).
  21
  22 * [ARM64/Aarch64 devices (64 bit; Android 5+)](https://firefox-ci-tc.services.mozilla.com/api/index/v1/task/project.mobile.fenix.v2.fennec-beta.latest/artifacts/public/build/arm64-v8a/geckoBeta/target.apk)
  23 * [ARM devices (32 bit; Android 5+)](https://firefox-ci-tc.services.mozilla.com/api/index/v1/task/project.mobile.fenix.v2.fennec-beta.latest/artifacts/public/build/armeabi-v7a/geckoBeta/target.apk)
  24 * [x86_64 devices (64 bit; Android 5+)](https://firefox-ci-tc.services.mozilla.com/api/index/v1/task/project.mobile.fenix.v2.fennec-beta.latest/artifacts/public/build/x86_64/geckoBeta/target.apk)
  25 * [x86 devices (32 bit; Android 5+)](https://firefox-ci-tc.services.mozilla.com/api/index/v1/task/project.mobile.fenix.v2.fennec-beta.latest/artifacts/public/build/x86/geckoBeta/target.apk)
  26
  27 ## Nightly
  28
  29 The following links point to the latest *Fenix* (Firefox Preview) builds (Nightly; from `main`) that are setup to **replace** a *Fennec Nightly* (Firefox for Android - Nightly) release version (`org.mozilla.fennec_aurora`).
  30
  31 * [ARM64/Aarch64 devices (64 bit; Android 5+)](https://firefox-ci-tc.services.mozilla.com/api/index/v1/task/mobile.v2.fenix.nightly.latest.arm64-v8a/artifacts/public/build/arm64-v8a/target.apk)
  32 * [ARM devices (32 bit; Android 5+)](https://firefox-ci-tc.services.mozilla.com/api/index/v1/task/mobile.v2.fenix.nightly.latest.armeabi-v7a/artifacts/public/build/armeabi-v7a/target.apk)
  33 * [x86_64 devices (64 bit; Android 5+)](https://firefox-ci-tc.services.mozilla.com/api/index/v1/task/mobile.v2.fenix.nightly.latest.x86_64/artifacts/public/build/x86_64/target.apk)
  34 * [x86 devices (32 bit; Android 5+)](https://firefox-ci-tc.services.mozilla.com/api/index/v1/task/mobile.v2.fenix.nightly.latest.x86/artifacts/public/build/x86/target.apk)
  35
  36 ## 📝 Changelog
  37
  38 The data migration work is tracked on the following project board:
  39 https://github.com/orgs/mozilla-mobile/projects/40
  40
  41 * **2019-09-05** - The first [migration builds](https://tools.taskcluster.net/index/project.mobile.fenix.v2.fennec-production/latest) 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.
  42 * **2019-10-22** - First iteration of migration code to migrate history, bookmarks and open tabs landed in builds.
  43 * **2019-11-02** - Firefox Account users remain logged in after migrating to Fenix.
  44
  45 ## 💻 Development
  46
  47 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.
  48
  49 In the example commands below, we assume you are replacing a **Fennec Nightly** build with a **Fenix Nightly** build.
  50
  51 ## Fennec
  52
  53 Download the latest version of Fennec:
  54
  55  - [ARM64/Aarch64 devices (64 bit; Android 5+)](https://archive.mozilla.org/pub/mobile/nightly/latest-mozilla-esr68-android-aarch64/)
  56  - [ARM devices (32 bit; Android 5+)](https://archive.mozilla.org/pub/mobile/nightly/latest-mozilla-esr68-android-api-16/)
  57  - [x86_64 devices (64 bit; Android 5+)](https://archive.mozilla.org/pub/mobile/nightly/latest-mozilla-esr68-android-x86_64/)
  58  - [x86 devices (32 bit; Android 5+)](https://archive.mozilla.org/pub/mobile/nightly/latest-mozilla-esr68-android-x86/)
  59
  60 Strip out the original signature:
  61
  62 ```
  63 zip --delete fennec.apk "META-INF/*"
  64 ```
  65
  66 Re-sign the APK with your own debug key (that will also be used later for Fenix):
  67
  68 ```
  69 jarsigner -verbose -keystore ~/.android/debug.keystore -storepass android -keypass android fennec.apk androiddebugkey
  70 ```
  71
  72 You can now install this APk that is ready to be used for migration:
  73
  74 ```
  75 adb install fennec.apk
  76 ```
  77
  78 ## Fenix
  79
  80 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 Fennec APK:
  81
  82 ```groovy
  83 android {
  84   buildTypes {
  85     fennecNightly {
  86       signingConfig signingConfigs.debug
  87     }
  88   }
  89 }
  90 ```
  91
  92 Follow the build instructions in the [README](https://github.com/mozilla-mobile/fenix/blob/main/README.md) to get a Fenix build setup.
  93
  94 Now select the `geckoNightlyFennecNightly` build variant in Android Studio and deploy it. This build should have replaced your Fennec build now.
  95
  96 ## Sample browser
  97
  98 When working on migration code that lives in the [Android Components repository](https://github.com/mozilla-mobile/android-components) it can be helpful to replace a local Fennec build with the sample browser (instead of Fenix). The following setup is needed for that.
  99
 100 Add the sharedUserId to the AndroidManifest.xml of sample browser:
 101
 102 ```XML
 103 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
 104     xmlns:tools="http://schemas.android.com/tools"
 105     android:sharedUserId="org.mozilla.fennec_$USERNAME.sharedID"
 106     [..]
 107 ```
 108
 109 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).
 110
 111 ```Groovy
 112     defaultConfig {
 113         applicationId "org.mozilla.fennec_$USERNAME"
 114         [..]
 115         versionCode 2100000000
 116 ```
 117
 118
 119
 120 Click on "Sync Project with Gradle Files" and deploy the sample browser. This build should have replaced your Fennec build now.
 121
 122 ## Emulator snapshots
 123
 124 When testing migration code the following process has to be repeated multiple times:
 125
 126 * (1) Uninstall an already existing Fennec/Fenix installation
 127 * (2) Install Fennec
 128 * (3) Use Fennec to create the necessary data for testing the migration
 129 * (4) Install Fenix
 130 * (5) Debug / Test
 131
 132 Steps (1) to (3) can be quite time consuming. Emulator snapshots can help with that:
 133
 134 * 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`).
 135 * 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".
 136 * With the "Play" button you can always reset your emulator to that state and repeat the migration process.