[fenix] Bug 1812087 - Migrate Fenix wiki pages into the docs folder
Gabriel Luong
1 year ago
committed by
mergify[bot]
parent
e2b346c69f
commit
4fa35e3d37
@ -0,0 +1,7 @@
|
||||
Instructions to enable the "secret settings" in the Settings menu for Firefox Nightly. This lets you access "Secret Settings" and "Secret Debug Info" in the Settings menu.
|
||||
|
||||
1. Tap on three-dot menu in the toolbar
|
||||
2. Tap on Settings
|
||||
3. Scroll down and select "About Firefox Nightly"
|
||||
4. Tap the Firefox logo until you see the "Debug menu: (#) click(s) left to enable" helper message
|
||||
5. Once the Debug menu has been enabled, go back to Settings and you will see "Secret Settings" and "Secret Debug Info" menu items
|
||||
@ -0,0 +1,14 @@
|
||||
Explanations of common acronyms that are seen in the Fenix project boards and issues.
|
||||
|
||||
**AC**: "[Android Components](https://github.com/mozilla-mobile/android-components)", the Mozilla team responsible for componentization.
|
||||
|
||||
**AS**: "[Application Services](https://github.com/mozilla/application-services)", the Mozilla team responsible for sync and storage (logins, bookmarks, etc).
|
||||
|
||||
**CFR**: "Contextual feature recommendation", i.e. popup windows.
|
||||
|
||||
**CTA**: "Call to action", a marketing/product term for things that pop up and ask for user interaction.
|
||||
|
||||
**ETP**: "Enhanced tracking protection". The shield icon.
|
||||
|
||||
**PWA**: "[Progressive web application](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps)", Fenix can act as a host for these applications.
|
||||
|
||||
@ -0,0 +1,40 @@
|
||||
## Important
|
||||
* The main goal here is not to file an issue for every single distinct crash report, but to find regressions of new problems that need to be addressed.
|
||||
* Once you're familiar with the process this should not take more than 10 mins in the morning.
|
||||
* Quick links that you should check everyday [Sentry Query](https://sentry.io/organizations/mozilla/issues/?groupStatsPeriod=auto&page=0&project=6295546&query=is%3Aunresolved+level%3Afatal+firstSeen%3A-1w&sort=freq&statsPeriod=14d) and [Socorro Query](https://crash-stats.mozilla.org/topcrashers/?product=Fenix&days=3&_range_type=build&process_type=any)
|
||||
|
||||
## Things to note before starting:
|
||||
* Since we are focused on Java crashes, Sentry currently is the better choice.
|
||||
* Ignore `level:info` issues (blue labels in Sentry). These issues are informational only.
|
||||
|
||||
## What to do when monitoring crashes:
|
||||
* Look at Sentry Fenix-nightly overview. Go though trending issues. [Sentry Dashboard](https://sentry.io/organizations/mozilla/projects/fenix-nightly/?project=6295546).
|
||||
* Look at Sentry custom search [Sentry Query](https://sentry.io/organizations/mozilla/issues/?groupStatsPeriod=auto&page=0&project=6295546&query=is%3Aunresolved+level%3Afatal+firstSeen%3A-1w&sort=freq&statsPeriod=14d).
|
||||
* Sign up for https://groups.google.com/a/mozilla.org/g/stability to get a daily email on the stability of Fenix.
|
||||
|
||||
## How to determine a crash requires actions:
|
||||
* Crashes that have level either Fatal or Error.
|
||||
* Crashes that are occurring on latest Fenix and A-C versions.
|
||||
* Crashes that are spiking.
|
||||
* Crashes that are new.
|
||||
* Crashes that happen repeatedly and often.
|
||||
* Crashes that are happening to multiple users.
|
||||
|
||||
## When a crash report requires actions:
|
||||
* Is this a crash due to a recent change? If so, contact the developer.
|
||||
* The histogram on the right side can help determine this along with checking the Firefox-Beta and Firefox Sentry products.
|
||||
* Triage the crash to determine if the issue is real and requires a GitHub issue to track it.
|
||||
* When filing an issue add a link to it as a comment in the Sentry crash for the products (nightly, beta, release) where the crash appears.
|
||||
* If a GitHub issue is required to track the crash, put the issue in the [Android Team Backlog Staging Board](https://github.com/orgs/mozilla-mobile/projects/70).
|
||||
* Notify the relevant teams on Slack/Matrix that there's a new crash in Nightly that needs urgent attention, e.g. **#synced-client-integrations** for all things involving application services (A-S), **#nimbus-rust-sdk** for Nimbus, and **[GeckoView on Matrix](https://chat.mozilla.org/#/room/#geckoview:mozilla.org)**.
|
||||
|
||||
## What can you do to help when not monitoring crashes
|
||||
* If you recently landed a new module / change that is significant, contact the crash monitor so they are aware of it.
|
||||
|
||||
## Crash monitoring with Socorro
|
||||
* Look at [Top Crashers for Fenix Nightly](https://crash-stats.mozilla.org/topcrashers/?product=Fenix&days=3&_range_type=build&process_type=any) for reports on Nightly builds.
|
||||
* This will return zero results if GV build ID is greater than 3 days old. Change to the 7 day view and ask #releaseduty-mobile in Slack about the GV upgrade task being broken.
|
||||
* Use Sentry, GitHub, and Bugzilla to determine if the crash has already been reported. If a Bugzilla bug has been filed for a crash, a link to the bug should be listed in Socorro's "Bugzilla IDs" column.
|
||||
* If the crash is new and the volume is high, then consider filing an issue.
|
||||
* If the crash is a native crash, file a bug using the crash-stats Bugzilla tab from a crash ID.
|
||||
* If the crash is a Java crash, then consider opening an issue on GitHub.
|
||||
@ -0,0 +1,67 @@
|
||||
These are instructions for preparing a release branch for Fenix Beta release. For reference, the AC release checklist can be found at https://mozac.org/contributing/release-checklist.
|
||||
|
||||
## [Release Management] Creating a new Beta release branch
|
||||
**This part is 100% covered by the Release Management team. The dev team should not perform these steps.**
|
||||
|
||||
1. Create a branch name with the format `releases_v[beta_version].0.0` (for example: `releases_v87.0.0`) off of the `main` branch using the GitHub UI. `[beta_version]` should follow the Firefox Beta version number. See [Firefox Release Calendar](https://wiki.mozilla.org/Release_Management/Calendar).
|
||||
2. Verify that `version.txt` already refers to the Fenix Beta release version `[beta_version].0b1` in the `releases_v[beta_version].0.0` branch. Bump it manually if necessary.
|
||||
3. In the `main` branch, create a pull request to update `version.txt` to `[nightly_version].0b1`. Land the updated `version.txt` into `main` with a review from someone from RelMan (#releaseduty-mobile). See [#26177](https://github.com/mozilla-mobile/fenix/pull/26177) for example.
|
||||
4. Notify the dev team that they can start the new Nightly development cycle per the steps given in the next section ⬇️
|
||||
5. Once the new AC `v[beta_version].0b1` release is ready (see the [AC release checklist](https://mozac.org/contributing/release-checklist)), create a pull request targeting the `releases_v[beta_version].0.0` branch to pin the Android Components `VERSION` to `[beta_version].0b1`. The commit message should be `Set Android-Components version to [beta_version].0b1`.
|
||||
```diff
|
||||
diff --git a/buildSrc/src/main/java/AndroidComponents.kt b/buildSrc/src/main/java/AndroidComponents.kt
|
||||
--- a/buildSrc/src/main/java/AndroidComponents.kt
|
||||
+++ b/buildSrc/src/main/java/AndroidComponents.kt
|
||||
@@ -3,5 +3,5 @@
|
||||
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
|
||||
|
||||
object AndroidComponents {
|
||||
- const val VERSION = "110.0.20230115143320"
|
||||
+ const val VERSION = "110.0b1"
|
||||
}
|
||||
```
|
||||
6. Announce the new `releases_v[beta_version].0.0` branch on Slack in #releaseduty-mobile.
|
||||
7. Once the AC version bump has landed, create the new Fenix Beta release in [Ship-It](https://shipit.mozilla-releng.net/) per normal practice.
|
||||
|
||||
## [Dev Team] Starting the next Nightly development cycle
|
||||
**Release Management will take care of updating `version.txt` for the `main` branch in order to prepare beta versions of our Nightly release.**
|
||||
|
||||
### [Dev Team] Create new milestone
|
||||
|
||||
Create a new [milestone](https://github.com/mozilla-mobile/fenix/milestones) for the `[nightly_version]` and close the existing `[beta_version]` milestone.
|
||||
|
||||
The milestone is an indicator of the Fenix version where the code related to the issue is landed, and does not need to reflect when the issue is closed by QA verified. This is useful for keeping track of when a feature is shipped.
|
||||
|
||||
Examine all the remaining open issues in the closed milestone to see if the issue should be closed or remove the tagged milestone depending on what is appropriate. If an issue is still in "eng:qa-needed", then it is fine to let it remain in the current closed milestone and open. If an issue clearly doesn't require "eng:qa-needed" (eg, Remove strings in 104, Fix typo, etc), then remove the label and close the issue. If an issue is clearly unresolved due to being reopened by QA and work still continues, remove the milestone.
|
||||
|
||||
### [Dev Team] Renew telemetry
|
||||
|
||||
After the Beta cut, another task is to renew/remove all soon to expire telemetry probes. What we're looking for is to create a list of telemetry that will expire in `[nightly_version add 2]`. See [Firefox Release Calendar](https://wiki.mozilla.org/Release_Management/Calendar) for the current Release version. There is a script that will help with finding these soon to expire telemetry.
|
||||
|
||||
1. Use the helper in tools folder `python3 data_renewal_generate.py [nightly_version add 2]` to detected and generate files that will help create the following files:
|
||||
- `[nightly_version add 2]`_expiry_list.csv
|
||||
- `[nightly_version add 2]`_renewal_request.txt
|
||||
2. Upload the `[nightly_version add 2]`_expiry_list.csv to Google sheet in this [shared Google Drive](https://drive.google.com/drive/folders/1_ertMvn59eE9JmN721RqOjW6nNtxq9oS?usp=sharing) and contact product to review. For each telemetry listed answer decide for:
|
||||
- Renew the metric (Recommendation is to use nightly_version + 12)
|
||||
- Choose not to renew (but not delete)
|
||||
- Choose to remove the metric
|
||||
- Renew the metric and set to never expire (this should only be for business critical metrics)
|
||||
3. Note that `metrics.yaml` is also modified. Once the review is over, continue to modify `metrics.yaml` to match the decision made in the Google sheet. Make sure to add the PR link and if the telemetry never expires, add the email of the owner as contact.
|
||||
4. File an issue for telemetry renewal so that a patch can target it and assign the issue to Product for increased visibility, as a reminder to to address the expiring metrics. See [issue 28190](https://github.com/mozilla-mobile/fenix/issues/28190) for an example.
|
||||
5. Create a PR for review. Modify `[nightly_version add 2]`_renewal_request.txt and paste it to the PR for data review. This comment can be auto-generated using the filled `[nightly_version add 2]`_expiry_list.csv and the `tools/data_renewal_request.py` helper. Copy the filled CSV into the tools directory and run the script to create a `[nightly_version add 2]`_filled_renewal_request.txt file that will contain the text required for data review. Make sure it includes (or add manually if necessary):
|
||||
- When will this collection now expire?
|
||||
- Why was the initial period of collection insufficient?
|
||||
6. Please also check if you're responsible for Focus telemetry renewal.
|
||||
|
||||
### [Dev Team] Remove unused strings
|
||||
|
||||
Now that we made the Beta cut, we can remove all the unused strings marked moz:removedIn <= `[release_version subtract 1]`. `[release_version]` should follow the Firefox Release version. See [Firefox Release Calendar](https://wiki.mozilla.org/Release_Management/Calendar) for the current Release version.
|
||||
|
||||
1. File a GitHub issue named "Remove all unused strings marked moz:removedIn <= `[release_version subtract 1]`".
|
||||
2. Search and remove all strings marked `moz:removedIn="[release_version subtract 1]"`.
|
||||
3. Put up a pull request.
|
||||
4. Please also check if you're responsible for Focus as well.
|
||||
|
||||
### Ask for Help
|
||||
|
||||
If you run into any problems, please ask any questions on Slack in #releaseduty-mobile.
|
||||
@ -0,0 +1,23 @@
|
||||
## This document outlines how data is collected in Firefox Preview.
|
||||
|
||||
### Telemetry
|
||||
|
||||
When a user has "Telemetry" enabled under Data Choices in the browser settings, Firefox Preview sends a "core" ping and an "event" ping to Mozilla's telemetry service. "core" ping using the same format documented on firefox-source-docs.mozilla.org.
|
||||
|
||||
[Here](https://github.com/mozilla-mobile/fenix/blob/master/docs/metrics.md) is a list of Event Pings, Metrics Pings, and Activation Pings.
|
||||
|
||||
**User can disable telemetry by turning the Telemetry toggle off under Data Choices.**
|
||||
|
||||
|
||||
***
|
||||
### Adjust
|
||||
|
||||
See [here](https://github.com/mozilla-mobile/fenix/wiki/Adjust-Usage) for details on Adjust usage in Firefox Preview.
|
||||
|
||||
***
|
||||
|
||||
### Sentry
|
||||
|
||||
Sentry collects a stack trace for each crash in Fenix.
|
||||
|
||||
If the user has "Telemetry" enabled under Data Choices in the browser settings, then Sentry collects breadcrumbs containing the name of each Android Fragment in the app. This helps an engineer diagnose the cause of the crash by seeing the internal names of screens visited before the crash occurred, i.e. Browser, Search, Home, etc. No information is stored about any arguments passed to any Fragments.
|
||||
@ -0,0 +1,23 @@
|
||||
It's important to know where we require tests and where they don't add significant value. This document intends to lay out that distinction.
|
||||
|
||||
In general, it's not necessary to test that the Android framework does what it says it does. If a code path sets the value of a TextView, one does not need to write an Espresso or Robolectric test to check that the TextView was set. This is why the Android framework team at Google has tests. Espresso tests are expensive in terms of runtime and should be used to ensure that all units of our software are correctly integrated together as a whole. Even Robolectric imposes a noticeable cost on test runtime, but it has proper uses.
|
||||
|
||||
### Components
|
||||
|
||||
Our app architecture is tied together by components that render UI. Generally, it's smart to write a set of unit tests for every UI component, but to mock the view. This can be accomplished by creating a Spy for the component. One may observe inputs and outputs of the component under test using RxKotlin TestObservers.
|
||||
|
||||
When testing Components, it's important to test any significant logic. If a reducer has more logic than mere Kotlin copy() operators, it should be tested.
|
||||
|
||||
### UIViews
|
||||
|
||||
When testing UIViews, we don't need to verify TextView set calls are made, but we should verify any branching logic that exists. If the ViewState is not basically ready to display, those transformations probably belong in the component and should be tested there. If the UIView class is simply a straight conduit from the ViewState directly to the UI, then there is no need for unit tests.
|
||||
|
||||
### Fragments
|
||||
|
||||
Fragments can get complicated. In theory, there should not be much View logic if the architecture is correctly integrated. One can mock out any components and the extension methods which perform layout and then use Robolectric to verify significant logic.
|
||||
|
||||
Generally, there shouldn't be large, branching blocks directly inside Android lifecycle callbacks. These should be broken out into methods, which can be tested on their own.
|
||||
|
||||
### Activities
|
||||
|
||||
Activities should exist only as entry points to the app in order to display fragments. The logic should be limited and should be testable as Robolectric tests with TestNavigators for testing navigation.
|
||||
@ -0,0 +1,134 @@
|
||||
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, ..).
|
||||
|
||||
## Release
|
||||
|
||||
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`).
|
||||
|
||||
* [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)
|
||||
* [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)
|
||||
* [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)
|
||||
* [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)
|
||||
|
||||
## Beta
|
||||
|
||||
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`).
|
||||
|
||||
* [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)
|
||||
* [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)
|
||||
* [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)
|
||||
* [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)
|
||||
|
||||
## Nightly
|
||||
|
||||
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`).
|
||||
|
||||
* [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)
|
||||
* [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)
|
||||
* [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)
|
||||
* [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)
|
||||
|
||||
# 📝 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](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.
|
||||
* **2019-10-22** - First iteration of migration code to migrate history, bookmarks and open tabs landed in builds.
|
||||
* **2019-11-02** - Firefox Account users remain logged in after migrating to Fenix.
|
||||
|
||||
# 💻 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.
|
||||
|
||||
In the example commands below, we assume you are replacing a **Fennec Nightly** build with a **Fenix Nightly** build.
|
||||
|
||||
## Fennec
|
||||
|
||||
Download the latest version of Fennec:
|
||||
|
||||
- [ARM64/Aarch64 devices (64 bit; Android 5+)](https://archive.mozilla.org/pub/mobile/nightly/latest-mozilla-esr68-android-aarch64/)
|
||||
- [ARM devices (32 bit; Android 5+)](https://archive.mozilla.org/pub/mobile/nightly/latest-mozilla-esr68-android-api-16/)
|
||||
- [x86_64 devices (64 bit; Android 5+)](https://archive.mozilla.org/pub/mobile/nightly/latest-mozilla-esr68-android-x86_64/)
|
||||
- [x86 devices (32 bit; Android 5+)](https://archive.mozilla.org/pub/mobile/nightly/latest-mozilla-esr68-android-x86/)
|
||||
|
||||
Strip out the original signature:
|
||||
|
||||
```
|
||||
zip --delete fennec.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 fennec.apk androiddebugkey
|
||||
```
|
||||
|
||||
You can now install this APk that is ready to be used for migration:
|
||||
|
||||
```
|
||||
adb install fennec.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 Fennec APK:
|
||||
|
||||
```groovy
|
||||
android {
|
||||
buildTypes {
|
||||
fennecNightly {
|
||||
signingConfig signingConfigs.debug
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Follow the build instructions in the [README](https://github.com/mozilla-mobile/fenix/blob/main/README.md) to get a Fenix build setup.
|
||||
|
||||
Now select the `geckoNightlyFennecNightly` 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](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.
|
||||
|
||||
Add the sharedUserId to the AndroidManifest.xml of sample browser:
|
||||
|
||||
```XML
|
||||
<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).
|
||||
|
||||
```Groovy
|
||||
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.
|
||||
@ -0,0 +1,12 @@
|
||||
Follow instructions in https://experimenter.info/mobile-feature-api. Example implementation [here](https://github.com/mozilla-mobile/fenix/pull/23996)
|
||||
|
||||
Nimbus FML https://experimenter.info/fml-spec/
|
||||
|
||||
|
||||
There are some clarification on how to test your Nimbus implementation:
|
||||
1. Add `nimbus.remote-settings.url=https://settings-cdn.stage.mozaws.net` to local.properties.
|
||||
2. After building Fenix, make sure you turn on `Secret Settings` -> `Use Nimbus Preview Collections`.
|
||||
3. The experiment in https://stage.experimenter.nonprod.dataops.mozgcp.net/nimbus/ does not have to be live for the test. In preview is sufficient.
|
||||
4. Example of a test is [here](https://stage.experimenter.nonprod.dataops.mozgcp.net/nimbus/unified-search-test)
|
||||
5. Make sure you archive the test after you're done with it.
|
||||
6. In your PR, make sure to submit the change for .experimenter.yaml as well.
|
||||
@ -0,0 +1,51 @@
|
||||
To profile background threads using the Firefox Profiler, you need to specify their names. It uses a case-insensitive substring match, e.g. specifying `default` will match all threads in the kotlin default dispatcher which have a name like, `DefaultDispatcher-worker-*`. This document is a list of the threads in fenix (via `ThreadGroup.list()` as of Mar 2022) to make using this functionality easier:
|
||||
```
|
||||
AutoSave-thread-1
|
||||
BrowserIcons-thread-1
|
||||
BrowserIcons-thread-2
|
||||
BrowserIcons-thread-3
|
||||
BrowserStore-thread-1
|
||||
ConnectivityThread
|
||||
DefaultDispatcher-worker-1
|
||||
DefaultDispatcher-worker-2
|
||||
DefaultDispatcher-worker-3
|
||||
DefaultDispatcher-worker-4
|
||||
DefaultDispatcher-worker-5
|
||||
DefaultDispatcher-worker-6
|
||||
DefaultDispatcher-worker-7
|
||||
DefaultDispatcher-worker-8
|
||||
FinalizerDaemon
|
||||
FinalizerWatchdogDaemon
|
||||
FxaAccountManager-thread-1
|
||||
Gecko
|
||||
GeckoInputConnection
|
||||
GleanAPIPool
|
||||
HeapTaskDaemon
|
||||
HistoryMetadataService-thread-1
|
||||
LeakCanary-Heap-Dump
|
||||
NimbusDbScope-thread-1
|
||||
NimbusFetchScope-thread-1
|
||||
PlacesStorageWriteScope-thread-1
|
||||
ReferenceQueueDaemon
|
||||
ThumbnailStorage-thread-1
|
||||
ThumbnailStorage-thread-2
|
||||
ThumbnailStorage-thread-3
|
||||
WM.task-1
|
||||
WM.task-2
|
||||
WM.task-3
|
||||
WM.task-4
|
||||
androidx.work-1
|
||||
androidx.work-2
|
||||
arch_disk_io_0
|
||||
arch_disk_io_1
|
||||
arch_disk_io_2
|
||||
arch_disk_io_3
|
||||
glean.MetricsPingScheduler
|
||||
main
|
||||
pool-23-thread-1
|
||||
pool-9-thread-1
|
||||
pool-9-thread-2
|
||||
queued-work-looper
|
||||
```
|
||||
|
||||
Note that `arch_disk_io_*` represents the kotlin io dispatcher.
|
||||
@ -0,0 +1,54 @@
|
||||
# Retrieving crash reports from the application
|
||||
* Open Firefox
|
||||
* Tap on the `3 dot menu`
|
||||
* Tap `Settings`
|
||||
* Scroll to the bottom of Settings
|
||||
* Tap `About Firefox`
|
||||
* Tap `Crashes`
|
||||
* Tap on the Socorro link
|
||||
* Copy and paste that address into a new [Github Issue: 🐞 Bug report](https://github.com/mozilla-mobile/fenix/issues/new/choose) or an existing issue
|
||||
* If you have many crash reports it can be helpful to include several of the recent crash URLs
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
# Using adb logcat to get crash information
|
||||
|
||||
Please use the above directions as a first way to get info. Use the following directions if your crash does not show up in the crash window of Firefox or if the crash prevents you from accessing the settings of Firefox.
|
||||
|
||||
To get information about a crash you will need an Android device that reproduces a crash, a computer running Windows, macOS or Linux and a USB cable that connects your device to your computer.
|
||||
|
||||
## Configuring your phone
|
||||
* Enable Developer Mode
|
||||
* On stock Android open the Android Settings and use the search at the top to find `build number`
|
||||
* Tap the build number 7 times
|
||||
* For other devices use your favorite search engine or YouTube to find steps for your device.
|
||||
* Enable Android USB debugging
|
||||
* On stock Android Open the Android Settings and use the search at the top to find `USB debugging` and enable it
|
||||
* Connect your device to the computer using a USB cable
|
||||
|
||||
## Downloading the Android SDK Platform tools
|
||||
* Download the [Android SDK Platform tools](https://developer.android.com/studio/releases/platform-tools) for your operating system
|
||||
* Use your operating system tools to extract the zip file that was downloaded
|
||||
|
||||
## Checking that adb can see your phone and is authorized
|
||||
* Connect your device to the computer using a USB cable
|
||||
* Open a command prompt or terminal and change to the directory to the platform tools directory that was extracted
|
||||
* On Windows run the command `adb devices` on macOS and Linux run `./adb devices`
|
||||
* If it returns unauthorized you will need to authorize the phone to connect to the computer by accepting the connection dialog on the phone
|
||||
|
||||
## Reproducing the crash
|
||||
* Connect your device to the computer using a USB cable
|
||||
* Open a command prompt or terminal and change to the directory to the platform tools directory that was extracted
|
||||
* On Windows run `adb logcat -v time` on macOS and Linux run `./adb logcat -v time`
|
||||
* Reproduce the crash
|
||||
* Submit the crash report(s)
|
||||
* Unplug the device
|
||||
* Copy all the information in the terminal
|
||||
* Paste the information into a Gist https://gist.github.com/ and save logcat information
|
||||
* Add the Gist URL to the issue for the crash
|
||||
|
||||
## Optional Cleanup
|
||||
* It is recommended to disable USB debugging once you are done collecting this information
|
||||
* You can remove the Android SDK Platform tools by deleting the folders and zip file
|
||||
@ -0,0 +1,35 @@
|
||||
To help find metrics in the [Glean Dictionary] and other tools, metrics should contain tag metadata corresponding to the
|
||||
feature area(s) that they belong to. In the case of Firefox for Android, tag information is based off of the GitHub feature labels for this repository:
|
||||
|
||||
https://github.com/mozilla-mobile/fenix/labels?q=feature%3A
|
||||
|
||||
You can see how tag information is rendered here:
|
||||
|
||||
https://dictionary.telemetry.mozilla.org/apps/fenix?itemType=tags&page=1
|
||||
|
||||
## Adding feature tags to metrics
|
||||
|
||||
Adding tag information to a metric used to involve editing the [Glean Annotations repository], but you can now add this
|
||||
information directly when adding or modifying `metrics.yaml`. Just add a section called `metadata` to the metric and add a list of tags that correspond to it.
|
||||
|
||||
For example:
|
||||
|
||||
```yaml
|
||||
search_bar_tapped:
|
||||
type: event
|
||||
description: |
|
||||
A user tapped the search bar
|
||||
metadata:
|
||||
tags:
|
||||
- Search
|
||||
...
|
||||
```
|
||||
|
||||
## Updating the feature tags
|
||||
|
||||
The set of valid tags is documented in a file called `tags.yaml`, but should never be updated by hand.
|
||||
If a feature labels is ever added or removed, you can synchronize the tags file in the source tree by running `./tools/update-glean-tags.py` in the root of the repository.
|
||||
Note that a tag *must* be specified in `tags.yaml` for it to be usable in a metric, so if a tag is removed from `tags.yaml` all uses of it must be removed from `metrics.yaml`.
|
||||
|
||||
[Glean Dictionary]: https://dictionary.telemetry.mozilla.org
|
||||
[Glean Annotations repository]: https://github.com/mozilla/glean-annotations
|
||||
@ -0,0 +1,77 @@
|
||||
Watch a step by step [video](https://user-images.githubusercontent.com/6579541/170517089-7266b93e-7ff8-4ebb-ae01-4f2a7e558c66.mp4)
|
||||
|
||||
1. To send data by default. apply this patch:
|
||||
``` diff
|
||||
|
||||
diff --git a/app/src/main/java/org/mozilla/fenix/FenixApplication.kt b/app/src/main/java/org/mozilla/fenix/FenixApplication.kt
|
||||
|
||||
index 4cb11de43..0c6fab136 100644
|
||||
|
||||
--- a/app/src/main/java/org/mozilla/fenix/FenixApplication.kt
|
||||
|
||||
+++ b/app/src/main/java/org/mozilla/fenix/FenixApplication.kt
|
||||
|
||||
@@ -293,9 +293,7 @@ open class FenixApplication : LocaleAwareApplication(), Provider {
|
||||
|
||||
}
|
||||
|
||||
|
||||
|
||||
private fun startMetricsIfEnabled() {
|
||||
|
||||
- if (settings().isTelemetryEnabled) {
|
||||
|
||||
- components.analytics.metrics.start(MetricServiceType.Data)
|
||||
|
||||
- }
|
||||
|
||||
+ components.analytics.metrics.start(MetricServiceType.Data)
|
||||
|
||||
|
||||
|
||||
if (settings().isMarketingTelemetryEnabled) {
|
||||
|
||||
components.analytics.metrics.start(MetricServiceType.Marketing)
|
||||
|
||||
diff --git a/app/src/main/java/org/mozilla/fenix/components/metrics/MetricController.kt b/app/src/main/java/org/mozilla/fenix/components/metrics/MetricController.kt
|
||||
|
||||
index c38ebb62d..3ae102d97 100644
|
||||
|
||||
--- a/app/src/main/java/org/mozilla/fenix/components/metrics/MetricController.kt
|
||||
|
||||
+++ b/app/src/main/java/org/mozilla/fenix/components/metrics/MetricController.kt
|
||||
|
||||
@@ -50,7 +50,7 @@ interface MetricController {
|
||||
|
||||
isMarketingDataTelemetryEnabled: () -> Boolean,
|
||||
|
||||
settings: Settings
|
||||
|
||||
): MetricController {
|
||||
|
||||
- return if (BuildConfig.TELEMETRY) {
|
||||
|
||||
+ return if (true) {
|
||||
|
||||
ReleaseMetricController(
|
||||
|
||||
services,
|
||||
|
||||
isDataTelemetryEnabled,
|
||||
|
||||
```
|
||||
|
||||
2. Trigger your pings.
|
||||
3. Sends the ping sing this command:
|
||||
```
|
||||
adb shell am start -n org.mozilla.fenix.debug/mozilla.telemetry.glean.debug.GleanDebugActivity \
|
||||
--ez logPings true \
|
||||
--es sendPing metrics \
|
||||
--es debugViewTag test-metrics-ping
|
||||
```
|
||||
4. See the results on https://debug-ping-preview.firebaseapp.com/
|
||||
|
||||
The parameters `sendPing` can be `metrics` or `events` depending or your needs, additionally `debugViewTag` can be customize to your preferred tag `debugViewTag your-metrics-ping`.
|
||||
|
||||
|
||||
|
||||
@ -0,0 +1,27 @@
|
||||
## Marking an unused string to be removed
|
||||
|
||||
Removing strings manually could cause crashes in **Beta** and **Release** versions 💥 , as the removed strings could be [uplifted to release branches](https://github.com/mozilla-mobile/fenix/pull/20364) by mistake, where strings are still needed. For this reason, we need a special process to remove them.
|
||||
|
||||
Any landed string that is not removed while in development in Nightly will persist through 3 Firefox releases (Nightly, Beta, Release) before we can remove them from our code base. For example,
|
||||
if you want to remove a string that has already shipped prior to **Firefox Nightly 93**, the same string will still be in-use in **Firefox Beta 92** and **Firefox Release 91**. This means the string will be marked as unused and removed in 93 while still riding the train, and it can be removed safely when **Firefox Release 93** no longer ships, for instance, **Firefox Release 94** and beyond.
|
||||
|
||||
To keep us safe when you want to remove strings from nightly:
|
||||
|
||||
1. Add these attribute to the target strings `moz:removedIn="<<ACTUAL_NIGHTLY_VERSION>>"` and `tools:ignore="UnusedResources"`.
|
||||
|
||||
```xml
|
||||
<string name="onboarding_close" moz:removedIn="93" tools:ignore="UnusedResources">Close</string>
|
||||
```
|
||||
Example PR https://github.com/mozilla-mobile/fenix/pull/20980.
|
||||
|
||||
## When to remove an unused string and how
|
||||
|
||||
Strings that have been tagged with `moz:removedIn` attributes are safe to be removed after the marked version is no longer shipping and no longer in-use or needed.
|
||||
|
||||
Consult the [Firefox release calendar](https://wiki.mozilla.org/Release_Management/Calendar). Let's say the Beta cut just happened and we are at Firefox Nightly 109, Firefox Beta 108 and Firefox Release 107. Everything marked with `moz:removedIn` <= 106 can now be removed.
|
||||
|
||||
You only need to remove the en-US strings within [values/strings.xml](https://searchfox.org/mozilla-mobile/source/fenix/app/src/main/res/values/strings.xml), and this change will propagate to the other locales.
|
||||
|
||||
## Future
|
||||
|
||||
It would be nice to add some automatization to delete the strings that have the `moz:removedIn` attributes where a full cycle has happen (3 releases versions from the actual release version).
|
||||
Loading…
Reference in New Issue