From 4d5604930ed183db3810c2fe120acdaf297a8681 Mon Sep 17 00:00:00 2001 From: Gabriel Luong Date: Wed, 14 Feb 2024 02:48:21 -0500 Subject: [PATCH] Bug 1880216 - Migrate Fenix docs into Sphinx. r=owlish,geckoview-reviewers,android-reviewers Differential Revision: https://phabricator.services.mozilla.com/D201854 --- docs/config.yml | 1 + mobile/android/fenix/docs/Acronym-dictionary.md | 2 + .../docs/Addressing-a-performance-regression.md | 2 + .../android/fenix/docs/Architecture-Decisions.md | 24 +++++----- mobile/android/fenix/docs/Crash-Monitoring.md | 2 + .../fenix/docs/Creating-a-release-branch.md | 2 + mobile/android/fenix/docs/Data-Practices.md | 10 ++-- mobile/android/fenix/docs/Development-Test-Plan.md | 10 ++-- mobile/android/fenix/docs/Fennec-Migration.md | 8 ++-- .../docs/Firefox-for-Android-Team-Processes.md | 1 + .../android/fenix/docs/Implementing-Telemetry.md | 2 + .../fenix/docs/Implementing-a-Nimbus-Experiment.md | 2 + mobile/android/fenix/docs/List-of-fenix-threads.md | 2 + .../fenix/docs/Logging-Crash-Information.md | 16 ++++--- mobile/android/fenix/docs/Metric-Feature-Tags.md | 2 + .../Secret-settings-debug-menu-instructions.md | 2 + .../Telemetry-implementation,-reviews,-renewals.md | 2 + mobile/android/fenix/docs/Test-telemetry-pings.md | 2 + mobile/android/fenix/docs/Working-with-Strings.md | 2 + mobile/android/fenix/docs/adjust.md | 2 + mobile/android/fenix/docs/architecture-overview.md | 54 +++++++++++----------- mobile/android/fenix/docs/certificates.md | 2 +- mobile/android/fenix/docs/index.rst | 42 +++++++++++++++++ mobile/android/fenix/docs/l10nScreenshotsTests.md | 2 + mobile/android/fenix/docs/manual-testing.md | 2 +- mobile/android/fenix/docs/metrics.md | 2 +- mobile/android/fenix/docs/release-checklist.md | 2 + mobile/android/fenix/docs/syncIntegrationTests.md | 2 + mobile/android/moz.build | 1 + 29 files changed, 146 insertions(+), 59 deletions(-) create mode 100644 mobile/android/fenix/docs/index.rst diff --git a/docs/config.yml b/docs/config.yml index 0a4ed464d0c2..de461c9275ba 100644 --- a/docs/config.yml +++ b/docs/config.yml @@ -25,6 +25,7 @@ categories: - toolkit - js - mobile/android/geckoview + - mobile/android/fenix - dom/bindings/webidl - modules/libpref - networking diff --git a/mobile/android/fenix/docs/Acronym-dictionary.md b/mobile/android/fenix/docs/Acronym-dictionary.md index fbdfb65b7246..1b5c0f2d3fdb 100644 --- a/mobile/android/fenix/docs/Acronym-dictionary.md +++ b/mobile/android/fenix/docs/Acronym-dictionary.md @@ -1,3 +1,5 @@ +# Acronym Dictionary + 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. diff --git a/mobile/android/fenix/docs/Addressing-a-performance-regression.md b/mobile/android/fenix/docs/Addressing-a-performance-regression.md index 6037cfe5e513..27a391df037a 100644 --- a/mobile/android/fenix/docs/Addressing-a-performance-regression.md +++ b/mobile/android/fenix/docs/Addressing-a-performance-regression.md @@ -1,3 +1,5 @@ +# Addressing a performance regression + To keep Fenix in a good shape, the performance team weekly runs multiple performance tests to identify regressions. The results are kept and maintained [here](https://earthangel-b40313e5.influxcloud.net/d/s3AT6t7nk/fenix-startup-nightly-via-backfill-py?orgId=1). The main tests are: diff --git a/mobile/android/fenix/docs/Architecture-Decisions.md b/mobile/android/fenix/docs/Architecture-Decisions.md index 4bfd5c8f8f79..10c11dc2d697 100644 --- a/mobile/android/fenix/docs/Architecture-Decisions.md +++ b/mobile/android/fenix/docs/Architecture-Decisions.md @@ -1,3 +1,5 @@ +# Architecture Decisions + For an overview of our current architecture, please see [this document](https://github.com/mozilla-mobile/fenix/blob/master/docs/architecture-overview.md) --- @@ -6,13 +8,13 @@ These are some of the major architecture decisions we've made so far in Fenix. [ --- -# Overview +## Overview Several apps have suffered from insufficient attention to appropriate Android application architecture. This leads to spaghetti code, God objects, and leaky abstractions that make testing and maintaining our apps significantly more costly and challenging. --- -# Goals +## Goals Our architecture should: @@ -25,19 +27,19 @@ Our architecture should: --- -# Special Concerns +## Special Concerns As a browser, Fenix will need to interface with the Android Components and the GeckoView rendering engine. This means any architecture we choose must not require that all components of the app are implemented similarly. Also, our application state will need to synchronize with the engine’s state as the two will not always be in perfect sync due to hidden internals. --- -# Component Architecture +## Component Architecture -## Context +### Context A/B testing of layout and UX is a fundamental necessity of Fenix. We have a lot of hypotheses needing validation and actual usage data about what might make a browser better to acquire and retain more users. A lot of questionable decisions have been made in older mobile browsers that do not seem ideal for mobile devices, but we need data to tell us if our assumptions are correct. -## Decision +### Decision We did a review of modern app architectures used by companies throughout the tech industry and came across the Netflix "componentization" architecture. Netflix had a special desire to A/B test a lot of different layouts for their app's user interface and built their architecture for this express purpose. @@ -55,7 +57,7 @@ Here's a [sample repository](https://github.com/julianomoraes/componentizationAr The goal of software architecture is to minimize the cost of change. This decision is possibly the biggest factor for reducing the cost of changes to Fenix. It also plays well with the Android Components project, which provides so many of the components that will make up this project. -## Consequences +### Consequences We will package the UI into components which are reusable and can be remixed for A/B layout tests. @@ -65,13 +67,13 @@ One downside of this is the extra cost of getting contributors to avoid making U --- -# Localized, MVI (Model-View-Intent) Unidirectional Architecture +## Localized, MVI (Model-View-Intent) Unidirectional Architecture -## Context +### Context Race conditions are the bane of Android apps everywhere. They often happen because multiple systems cannot agree about state. -## Decision +### Decision The best solution is to have all state changes flow in a functional, reactive manner out from a single source of truth with careful thread locking as required. This solution will be familiar to anyone who has worked with Redux or Flux. @@ -83,7 +85,7 @@ However, unlike some MVI architectures, we will not focus on keeping a global Vi Here's a [state diagram of the MVI architecture](https://staltz.com/img/mvi-unidir-ui-arch.jpg). -## Consequences +### Consequences We will experiment with writing new components using MVI unidirectional principles. We will need to take care when passing data between components that we do not override a more authoritative source of truth. diff --git a/mobile/android/fenix/docs/Crash-Monitoring.md b/mobile/android/fenix/docs/Crash-Monitoring.md index e57319dbeca5..c40f3fcbe522 100644 --- a/mobile/android/fenix/docs/Crash-Monitoring.md +++ b/mobile/android/fenix/docs/Crash-Monitoring.md @@ -1,3 +1,5 @@ +# Crash Monitoring + ## 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. diff --git a/mobile/android/fenix/docs/Creating-a-release-branch.md b/mobile/android/fenix/docs/Creating-a-release-branch.md index 20ef4f0792db..16b5da7cd7b7 100644 --- a/mobile/android/fenix/docs/Creating-a-release-branch.md +++ b/mobile/android/fenix/docs/Creating-a-release-branch.md @@ -1 +1,3 @@ +# Creating a release branch + Please refer to https://mozac.org/contributing/release-checklist for creating a Beta release branch for the firefox-android monorepo. diff --git a/mobile/android/fenix/docs/Data-Practices.md b/mobile/android/fenix/docs/Data-Practices.md index 3ab132f5a3c8..78d71777ad4c 100644 --- a/mobile/android/fenix/docs/Data-Practices.md +++ b/mobile/android/fenix/docs/Data-Practices.md @@ -1,6 +1,8 @@ -## This document outlines how data is collected in Firefox Preview. +# Data Practices -### Telemetry +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. @@ -10,13 +12,13 @@ When a user has "Telemetry" enabled under Data Choices in the browser settings, *** -### Adjust +## Adjust See [here](https://github.com/mozilla-mobile/fenix/wiki/Adjust-Usage) for details on Adjust usage in Firefox Preview. *** -### Sentry +## Sentry Sentry collects a stack trace for each crash in Fenix. diff --git a/mobile/android/fenix/docs/Development-Test-Plan.md b/mobile/android/fenix/docs/Development-Test-Plan.md index 827cac59dd1a..4c94c709a314 100644 --- a/mobile/android/fenix/docs/Development-Test-Plan.md +++ b/mobile/android/fenix/docs/Development-Test-Plan.md @@ -1,23 +1,25 @@ +# Development Test Plan + 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 +## 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 +## 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 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 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. diff --git a/mobile/android/fenix/docs/Fennec-Migration.md b/mobile/android/fenix/docs/Fennec-Migration.md index 4e4af5899e64..3b8e488f2211 100644 --- a/mobile/android/fenix/docs/Fennec-Migration.md +++ b/mobile/android/fenix/docs/Fennec-Migration.md @@ -1,6 +1,8 @@ +# Fennec Migration + Project board: https://github.com/orgs/mozilla-mobile/projects/40 -# πŸ“± Testing +## πŸ“± 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, ..). @@ -31,7 +33,7 @@ The following links point to the latest *Fenix* (Firefox Preview) builds (Nightl * [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 +## πŸ“ Changelog The data migration work is tracked on the following project board: https://github.com/orgs/mozilla-mobile/projects/40 @@ -40,7 +42,7 @@ https://github.com/orgs/mozilla-mobile/projects/40 * **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 +## πŸ’» 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. diff --git a/mobile/android/fenix/docs/Firefox-for-Android-Team-Processes.md b/mobile/android/fenix/docs/Firefox-for-Android-Team-Processes.md index 7ee9891b0194..c28320118a92 100644 --- a/mobile/android/fenix/docs/Firefox-for-Android-Team-Processes.md +++ b/mobile/android/fenix/docs/Firefox-for-Android-Team-Processes.md @@ -1,3 +1,4 @@ +# Firefox for Android Team Processes ## Communication channels For internal Firefox Android communication start off in #mobile-android-team. diff --git a/mobile/android/fenix/docs/Implementing-Telemetry.md b/mobile/android/fenix/docs/Implementing-Telemetry.md index 2b65cd157829..a2dfff65718c 100644 --- a/mobile/android/fenix/docs/Implementing-Telemetry.md +++ b/mobile/android/fenix/docs/Implementing-Telemetry.md @@ -1,3 +1,5 @@ +# Implementing Telemetry + ## Things to note before implementation: * Understand that telemetry is important, it is not just a checkmark for feature completion. * The consumer of the telemetry is the data science team. diff --git a/mobile/android/fenix/docs/Implementing-a-Nimbus-Experiment.md b/mobile/android/fenix/docs/Implementing-a-Nimbus-Experiment.md index 4afd082c4b95..274206db28df 100644 --- a/mobile/android/fenix/docs/Implementing-a-Nimbus-Experiment.md +++ b/mobile/android/fenix/docs/Implementing-a-Nimbus-Experiment.md @@ -1,3 +1,5 @@ +# Implementing a Nimbus Experiment + 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/ diff --git a/mobile/android/fenix/docs/List-of-fenix-threads.md b/mobile/android/fenix/docs/List-of-fenix-threads.md index 719786151850..110eed4bdb1f 100644 --- a/mobile/android/fenix/docs/List-of-fenix-threads.md +++ b/mobile/android/fenix/docs/List-of-fenix-threads.md @@ -1,3 +1,5 @@ +# List of Fenix Threads + 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 diff --git a/mobile/android/fenix/docs/Logging-Crash-Information.md b/mobile/android/fenix/docs/Logging-Crash-Information.md index 79e6f071bab7..7222bd837531 100644 --- a/mobile/android/fenix/docs/Logging-Crash-Information.md +++ b/mobile/android/fenix/docs/Logging-Crash-Information.md @@ -1,4 +1,6 @@ -# Retrieving crash reports from the application +# Logging Crash Information + +## Retrieving crash reports from the application * Open Firefox * Tap on the `3 dot menu` * Tap `Settings` @@ -13,13 +15,13 @@ ![Screenshot showing where to find the settings and About Firefox elements of the app. The bulleted steps above contain the same information.](https://user-images.githubusercontent.com/250273/84347868-7bc9e980-ab68-11ea-990d-7284968c458a.png) ![Screenshot showing where to find the Crashes item in About Firefox and the Socorro link for the crash. ](https://user-images.githubusercontent.com/250273/84347924-a156f300-ab68-11ea-9d02-c984a030249f.png) -# Using adb logcat to get crash information +## 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 +### 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 @@ -28,17 +30,17 @@ To get information about a crash you will need an Android device that reproduces * 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 +### 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 +### 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 +### 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` @@ -49,6 +51,6 @@ To get information about a crash you will need an Android device that reproduces * 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 +### 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 diff --git a/mobile/android/fenix/docs/Metric-Feature-Tags.md b/mobile/android/fenix/docs/Metric-Feature-Tags.md index f377907f21c1..dbd7e177a662 100644 --- a/mobile/android/fenix/docs/Metric-Feature-Tags.md +++ b/mobile/android/fenix/docs/Metric-Feature-Tags.md @@ -1,3 +1,5 @@ +# Metric Feature Tags + 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: diff --git a/mobile/android/fenix/docs/Secret-settings-debug-menu-instructions.md b/mobile/android/fenix/docs/Secret-settings-debug-menu-instructions.md index 73584ee04292..c824d9cde33a 100644 --- a/mobile/android/fenix/docs/Secret-settings-debug-menu-instructions.md +++ b/mobile/android/fenix/docs/Secret-settings-debug-menu-instructions.md @@ -1,3 +1,5 @@ +# Debug settings menu instructions + 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 diff --git a/mobile/android/fenix/docs/Telemetry-implementation,-reviews,-renewals.md b/mobile/android/fenix/docs/Telemetry-implementation,-reviews,-renewals.md index 6164b85b1fd6..81f3ea5825f9 100644 --- a/mobile/android/fenix/docs/Telemetry-implementation,-reviews,-renewals.md +++ b/mobile/android/fenix/docs/Telemetry-implementation,-reviews,-renewals.md @@ -1,3 +1,5 @@ +# Telemetry - Implementation, Reviews, Renewals + See https://github.com/mozilla-mobile/fenix/wiki/Telemetry-Checklist for the steps to implement new probes. # Creating Glean Annotations diff --git a/mobile/android/fenix/docs/Test-telemetry-pings.md b/mobile/android/fenix/docs/Test-telemetry-pings.md index e35c72d60439..91d425617074 100644 --- a/mobile/android/fenix/docs/Test-telemetry-pings.md +++ b/mobile/android/fenix/docs/Test-telemetry-pings.md @@ -1,3 +1,5 @@ +# Test Telemetry Pings + 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 --git a/mobile/android/fenix/docs/Working-with-Strings.md b/mobile/android/fenix/docs/Working-with-Strings.md index 69deffd61c45..2e51fbd51647 100644 --- a/mobile/android/fenix/docs/Working-with-Strings.md +++ b/mobile/android/fenix/docs/Working-with-Strings.md @@ -1,3 +1,5 @@ +# Working with Strings + ## 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. diff --git a/mobile/android/fenix/docs/adjust.md b/mobile/android/fenix/docs/adjust.md index 87e57ef18862..e498771392ca 100644 --- a/mobile/android/fenix/docs/adjust.md +++ b/mobile/android/fenix/docs/adjust.md @@ -1,3 +1,5 @@ +# Adjust + Firefox for Android tracks certain types of installs using a third-party install tracking framework called Adjust. The intention is to determine the origin of Firefox for Android installs by answering the question, β€œDid this user on this device install Firefox for Android in response to a specific advertising campaign performed by Mozilla?” The framework consists of a software development kit (SDK) linked into Firefox for Android and a data-collecting Internet service backend run by the German company [adjust GmbH](https://www.adjust.com). The Adjust SDK is open source and MIT licensed. It is hosted at [https://github.com/adjust/android_sdk](https://github.com/adjust/android_sdk). Firefox for Android pulls in an unmodified copy of the SDK using Gradle. The [Dependencies.kt](https://github.com/mozilla-mobile/fenix/blob/main/buildSrc/src/main/java/Dependencies.kt) contains the version of the framework that is being used. The SDK is documented at [https://docs.adjust.com](https://docs.adjust.com). diff --git a/mobile/android/fenix/docs/architecture-overview.md b/mobile/android/fenix/docs/architecture-overview.md index 5a53f434ad33..ce4c7cc04672 100644 --- a/mobile/android/fenix/docs/architecture-overview.md +++ b/mobile/android/fenix/docs/architecture-overview.md @@ -1,16 +1,16 @@ -## Architecture Overview +# Architecture Overview -### Unidirectional data flow +## Unidirectional data flow Firefox for Android's presentation layer architecture is based on the concept of "unidirectional data flow." This is a popular approach in client side development, especially on the web, and is core to Redux, MVI, Elm Architecture, and Flux. Our architecture is not identical to any of these (and they are not identical to each other), but the base concepts are the same. For a basic understanding of the motivations and approach, see [the official Redux docs](https://redux.js.org/basics/data-flow). For an article on when unidirectional data flow is and is not a good approach, see [this](https://medium.com/swlh/the-case-for-flux-379b7d1982c6). These are both written from the perspective of React.js developers, but the concepts are largely the same. Our largest deviation from these architectures is that while they each recommend one large, global store of data, we have a single store per screen and several other global stores. This carries both benefits and drawbacks, which will be covered later in this document. -### Important types +## Important types -### Store +## Store -#### **Overview** +### **Overview** A store of State. @@ -20,7 +20,7 @@ Holds app State. Receives [Actions](#action), which are used to compute new State using [Reducers](#reducer) and can have [Middlewares](#middleware) attached which respond to and manipulate actions. -#### **Description** +### **Description** Maintains a [State](#state), a [Reducer](#reducer) to compute new State, and [Middleware](#middleware). Whenever the Store receives a new [Action](#action) via `store.dispatch(action)`, it will first pass the action through its chain of [Middleware](#middleware). These middleware can initiate side-effects in response, or even consume or change the action. Finally, the Store computes new State using previous State and the new action in the [Reducer](#reducer). The result is then stored as the new State, and published to all consumers of the store. It is recommended that consumers rely as much as possible on observing State updates from the store instead of reading State directly. This ensures that the most up to date State is always used. This can prevent subtle bugs around call order, as all observers are notified of the same State change before a new change is applied. @@ -31,13 +31,13 @@ Screen-based Stores should be created using [StoreProvider.get](https://github.c ------- -### State -#### **Overview** +## State +### **Overview** Description of the state of a screen or other area of the app. See [mozilla.components.lib.state.State](https://github.com/mozilla-mobile/firefox-android/blob/main/android-components/components/lib/state/src/main/java/mozilla/components/lib/state/State.kt) -#### **Description** +### **Description** Simple, immutable data object that contains all of the backing data required to display a screen. This should ideally only include Kotlin/Java data types which can be easily tested, avoiding Android platform types. This is especially true of large, expensive types like `Context` or `View` which should never be included in State. As much as possible, the State object should be an accurate, 1:1 representation of what is actually shown on the screen. That is to say, the screen should look exactly the same any time a State with the same values is emitted, regardless of any previous changes. This is not always possible as Android UI elements are very stateful, but it is a good goal to aim for. @@ -48,37 +48,37 @@ This also gives us a major advantage when debugging. If the UI looks wrong, chec ------- -### Action -#### **Overview** +## Action +### **Overview** Simple description of a State change or a user interaction. Dispatched to Stores. See [mozilla.components.lib.state.Action](https://github.com/mozilla-mobile/firefox-android/blob/main/android-components/components/lib/state/src/main/java/mozilla/components/lib/state/Action.kt) -#### **Description** +### **Description** Simple data object that carries information about a [State](#state) change to a [Store](#store). An Action describes _something that happened_, and carries any data relevant to that change. For example, `HistoryFragmentAction.ChangeEmptyState(isEmpty = true)`, captures that the State of the history fragment has become empty. ------- -### Reducer -#### **Overview** +## Reducer +### **Overview** Pure function used to create new [State](#state) objects. See [mozilla.components.lib.state.Reducer](https://github.com/mozilla-mobile/firefox-android/blob/main/android-components/components/lib/state/src/main/java/mozilla/components/lib/state/Reducer.kt) Referenced by: [Store](#store) -#### **Description** +### **Description** A function that accepts the previous State and an [Action](#action), then combines them in order to return the new State. It is important that all Reducers remain [pure](https://en.wikipedia.org/wiki/Pure_function). This allows us to test Reducers based only on their inputs, without requiring that we take into account the state of the rest of the app. Note that the Reducer is always called serially, as state could be lost if it were ever executed in parallel. ------- -### Middleware -#### **Overview** +## Middleware +### **Overview** A Middleware sits between the store and the reducer. It provides an extension point between dispatching an action, and the moment it reaches the reducer. -#### **Description** +### **Description** A Middleware responds to actions by performing side-effects, and can also be used to rewrite an Action, intercept an Action, or dispatch additional Actions. @@ -86,13 +86,13 @@ The Store will create a chain of Middleware instances and invoke them in order. ------- -### View -#### **Overview** +## View +### **Overview** Initializes UI elements, then updates them in response to [State](#state) changes Observes: [Store](#store) -#### **Description** +### **Description** The view defines the mapping of State to UI. This can include XML bindings, Composables, or anything in between. Views should be as dumb as possible, and should include little or no conditional logic outside of determining which branch of a view tree to display based on State. Ideally, each primitive value in a State object is set on some field of a UI element. @@ -135,15 +135,15 @@ For more context on when and why these components were removed, see [the RFC pro ------- -### Interactor -#### Overview +## Interactor +### Overview Called in response to a direct user action. Delegates to something else Called by: [View](#view) Calls: [Controllers](#controller), other Interactors -#### Description +### Description This is the first object called whenever the user performs an action. Typically this will result in code in the [View](#view) that looks something like `some_button.onClickListener { interactor.onSomeButtonClicked() } `. It is the Interactors job to delegate this button click to whichever object should handle it. Interactors may hold references to multiple other Interactors and Controllers, in which case they delegate specific methods to their appropriate handlers. This helps prevent bloated Controllers that both perform logic and delegate to other objects. @@ -154,15 +154,15 @@ Note that prior to the introduction of Controllers, Interactors handled the resp ------- -### Controller -#### Overview +## Controller +### Overview Determines how the app should be updated whenever something happens Called by: [Interactor](#interactor) Calls: [Store](#store), library code (e.g., forward a back-press to Android, trigger an FxA login, navigate to a new Fragment, use an Android Components UseCase, etc) -#### Description +### Description This is where much of the business logic of the app lives. Whenever called by an Interactor, a Controller will do one of the three following things: - Create a new [Action](#action) that describes the necessary change, and send it to the Store - Navigate to a new fragment via the NavController. Optionally include any state necessary to create this new fragment diff --git a/mobile/android/fenix/docs/certificates.md b/mobile/android/fenix/docs/certificates.md index 79e9f1737c03..1716bae036fa 100644 --- a/mobile/android/fenix/docs/certificates.md +++ b/mobile/android/fenix/docs/certificates.md @@ -3,7 +3,7 @@ The certificates for the official Fenix builds (`nightly`, `beta` and `production`) can be accessed from the `certificates` folder in the root of this repository -# Fingerprints +## Fingerprints Note: we currently only have the Fenix nightly deployed, and it's using the production key at the moment. diff --git a/mobile/android/fenix/docs/index.rst b/mobile/android/fenix/docs/index.rst new file mode 100644 index 000000000000..d6ddb75f626a --- /dev/null +++ b/mobile/android/fenix/docs/index.rst @@ -0,0 +1,42 @@ +================================= +Fenix +================================= + +Specific documentation on a few topics is available at: + +.. toctree:: + :maxdepth: 1 + + Acronym Dictionary + Addressing a performance regression + Architecture Decisions + Architecture Overview + Crash Monitoring + Creating a release branch + Data practises + Development Test Plan + Fennec Migration + Firebase Cloud Messaging for WebPush + Firefox for Android Team Processes + Guide to merging contributor PRs + Home + Implementing Telemetry + Implementing a Nimbus Experiment + List of Fenix Threads + Logging Crash Information + Metric Feature Tags + Debug settings menu instructions + Telemetry - Implementation, Reviews, Renewals + Test Telemetry Pings + Working with Strings + Adjust + Certificates + Crash Reporting + Experiments + l10n Screenshots Tests + Manual Testing + Metrics Definitions + Release Checklist + Substituting Local GeckoView + Sync Integration Tests + Telemetry diff --git a/mobile/android/fenix/docs/l10nScreenshotsTests.md b/mobile/android/fenix/docs/l10nScreenshotsTests.md index 76b577be57e5..637e2908953e 100644 --- a/mobile/android/fenix/docs/l10nScreenshotsTests.md +++ b/mobile/android/fenix/docs/l10nScreenshotsTests.md @@ -1,3 +1,5 @@ +# l10n Screenshots Test + ### Screenshtos Tests We are using [`screengrab`](https://docs.fastlane.tools/getting-started/android/screenshots/) which works with fastlane to automate the process of capturing screenshots. All the l10n screenshots are generated through the ui tests. These particular tests run as part of the screenshots package (`app/src/androidTest/mozilla/fenix/ui/screenshots`) diff --git a/mobile/android/fenix/docs/manual-testing.md b/mobile/android/fenix/docs/manual-testing.md index 6502152950bc..a2e9e059e65e 100644 --- a/mobile/android/fenix/docs/manual-testing.md +++ b/mobile/android/fenix/docs/manual-testing.md @@ -1,4 +1,4 @@ -Softvision Mobile QA - Fenix testing tasks and process +# Softvision Mobile QA - Fenix testing tasks and process ============= Overview diff --git a/mobile/android/fenix/docs/metrics.md b/mobile/android/fenix/docs/metrics.md index ea4ebedb2b14..24532087ccb9 100644 --- a/mobile/android/fenix/docs/metrics.md +++ b/mobile/android/fenix/docs/metrics.md @@ -1,4 +1,4 @@ -# Metrics definitions have moved +# Metrics Definitions Metrics definitions for Firefox for Android have moved to the [Glean Dictionary](https://dictionary.telemetry.mozilla.org/apps/fenix). diff --git a/mobile/android/fenix/docs/release-checklist.md b/mobile/android/fenix/docs/release-checklist.md index 5fccd930c704..0cd9121594b5 100644 --- a/mobile/android/fenix/docs/release-checklist.md +++ b/mobile/android/fenix/docs/release-checklist.md @@ -1,3 +1,5 @@ +# Release Checklist + ## Overview ## Firefox for Android roughly follows the [Firefox Gecko release schedule](https://wiki.mozilla.org/Release_Management/Calendar#Calendars). diff --git a/mobile/android/fenix/docs/syncIntegrationTests.md b/mobile/android/fenix/docs/syncIntegrationTests.md index 9ca9bd9c79c0..d16ac75a35d3 100644 --- a/mobile/android/fenix/docs/syncIntegrationTests.md +++ b/mobile/android/fenix/docs/syncIntegrationTests.md @@ -1,3 +1,5 @@ +# Sync Integration Tests + ### Sync Integration Tests The aim of these tests is to check that the synchronization is working between Fenix and Desktop. The intention is to add tests for History, Bookmarks, Tabs and Logins. At this moment only tests for History and Bookmarks are defined. diff --git a/mobile/android/moz.build b/mobile/android/moz.build index 689ec829338b..287167db1d7d 100644 --- a/mobile/android/moz.build +++ b/mobile/android/moz.build @@ -85,6 +85,7 @@ TEST_HARNESS_FILES.testing.mochitest.tests.junit += [ ] SPHINX_TREES["/mobile/android"] = "docs" +SPHINX_TREES["/mobile/android/fenix"] = "fenix/docs" with Files("docs/**"): SCHEDULES.exclusive = ["docs"] -- 2.11.4.GIT