Magic-Mirror/gecko-dev
1
0
Fork 0
mirror of https://github.com/mozilla/gecko-dev.git synced 2024-11-23 12:51:06 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Bug 1880227 - Migrate Focus docs into Sphinx. r=owlish,geckoview-reviewers,android-reviewers

Browse Source 
Differential Revision: https://phabricator.services.mozilla.com/D201855
This commit is contained in:
Gabriel Luong 2024-02-14 02:48:51 -05:00
parent 4d5604930e
commit 96be362f75
20 changed files with 112 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/config.yml
View File

@ -26,6 +26,7 @@ categories:
- js
- mobile/android/geckoview
- mobile/android/fenix
- mobile/android/focus-android
- dom/bindings/webidl
- modules/libpref
- networking

2
mobile/android/focus-android/docs/Adjust-Usage.md
View File

@ -1,3 +1,5 @@
# Adjust Usage
> **If there is anything in this document that is not clear, is incorrect, or that requires more detail, please file a request through a [Github](https://github.com/mozilla-mobile/focus-android/issues) or [Bugzilla](https://bugzilla.mozilla.org/enter_bug.cgi?product=Focus&component=General). Also feel free to submit corrections or additional information.**
Firefox Focus (but not Firefox Klar) tracks certain types of installs using a third-party install tracking framework called Adjust. The intention is to determine the origin of Firefox Focus installs by answering the question, “Did this user on this device install Firefox Focus in response to a specific advertising campaign performed by Mozilla?”

26
mobile/android/focus-android/docs/Architecture-Decisions.md
View File

@ -1,20 +1,22 @@
# Architecture Decisions
This is a collection of records for "architecturally significant" decisions. [Why?](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions)
---
# Observing state (LiveData)
## Observing state (LiveData)
* **ADR-3**
* Status: Accepted
* Affected version: 2.0+
## Context
### Context
During the refactoring of Focus for Android to support multitasking it became apparent that our callback-based approach wasn't good enough anymore. Previously the current browser state was used to update the UI only. Now with multiple concurrent sessions this state needed to be preserved and restored while the user switched between tabs. In addition to that we wanted to update multiple UI components based on the current state (partially) for which a single callback implementation became very complex fast.
Having observers for small chunks of data and a "reactive style" seemed to be a better approach. There are a lot of libraries that offer this functionality already, namely: RxJava, event buses (e.g. Otto and EventBus), Architecture Components (LiveData), Agera and others.
## Decision
### Decision
LiveData objects from Android's Architecture Components library are used to wrap data that updates asynchronously. UI components that depend on this data can either get the current state or subscribe in order to get updates whenever the data changes.
@ -25,19 +27,19 @@ Reasons:
* The library is pretty small.
* The library takes care of the Activity/Fragment lifecycle (Avoids common errors).
## Consequences
### Consequences
* LiveData was designed to be used with `ViewModel` instances. So far we do not use `ViewModel`s and are also observing LiveData objects from non-UI components. This is not problematic but can cause problems in future versions of the library - although unlikely.
---
# Browser engine: GeckoView vs. WebView
## Browser engine: GeckoView vs. WebView
* **ADR-2**
* Status: Accepted
* Affected app versions: 1.0+
## Context
### Context
To render web content Firefox Focus needs to use a "web browser engine". So far all browsers from Mozilla, and Firefox for Android in particular, are using the [Gecko engine](https://en.wikipedia.org/wiki/Gecko_(software)).
@ -45,7 +47,7 @@ Android itself ships with a [WebView](https://developer.android.com/guide/webapp
A number of existing Android browsers (e.g. Opera, Brave) are built on top of the Blink rendering engine or are a direct fork of Chromium.
## Decision
### Decision
Firefox Focus is going to be build on top of Android's WebView.
@ -57,23 +59,23 @@ In addition to that there will be a build configuration that uses GeckoView. The
Forking Chromium (or using Blink) was considered a too large investment in the prototype stage.
## Consequences
### Consequences
WebView has a complex API. Nevertheless it doesn't allow us to do heavy low-level customization that we could do if we would own the web browser engine (e.g. GeckoView). It remains to be seen whether this limitation will prevent feature development in a way that forces us to ship a browser engine with Focus for Android.
---
# Minimum supported Android version: 5.0+ (API 21+)
## Minimum supported Android version: 5.0+ (API 21+)
* **ADR-1**
* Status: Accepted
* Affected app versions: 1.0+
## Context
### Context
Every app needs to define a minimum supported SDK version. This is usually a trade-off between how many users can be reached ([Android version distribution](https://developer.android.com/about/dashboards/index.html)) and what platform features the app needs to support ([Android API level overview](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)).
## Decision
### Decision
Focus will support Android versions 5 and higher (API 21+). This decisions is primarily driven by the following platform features that are not available on earlier versions of Android:
@ -81,7 +83,7 @@ Focus will support Android versions 5 and higher (API 21+). This decisions is pr
* [UI features](https://developer.android.com/training/material/shadows-clipping.html) like `elevation` allow us to build and prototype a "material" UI without needing to backport functionality.
## Consequences
### Consequences
* At the point of writing this ADR we will cover 73.4% of the Android market with that decision [(*)](https://developer.android.com/about/dashboards/index.html).

2
mobile/android/focus-android/docs/Battery-Debugging.md
View File

@ -1,3 +1,5 @@
# Battery Debugging
Android Performance Profiling can be quite tricky in spite of the wealth of good tools available. This doc is to explain how to track down battery and performance issues.
## Battery Historian

4
mobile/android/focus-android/docs/Content-blocking.md
View File

@ -1,4 +1,6 @@
# Outdated Content.
# Content blocking
## Outdated Content.
Focus is using the same technology as Firefox for desktop, all the content blocking is happening inside of the Gecko engine web engine. content blocking list can be seen here https://github.com/mozilla-services/shavar-prod-lists.
## Tracking protection: lists and general overview

2
mobile/android/focus-android/docs/Crash-Reporting-with-Sentry.md
View File

@ -1,3 +1,5 @@
# Crash Reporting with Sentry
> **If there is anything in this document that is not clear, is incorrect, or that requires more detail, please file a request through a [Github](https://github.com/mozilla-mobile/focus-android/issues).**
Focus Android uses [Sentry](https://sentry.io) for crash and exception reporting. This kind of reporting gives Mozilla invaluable insight as to why Focus crashes or incorrectly behaves. It is one of the key methods we use to improve the product in terms of stability.

6
mobile/android/focus-android/docs/Development-Custom-GeckoView.md
View File

@ -1,3 +1,5 @@
# Development with Custom GeckoView
If you are an engineer working on Gecko(View) then you might be interested in building Focus/Klar with your own build of GeckoView.
For this you will need to:
@ -7,7 +9,7 @@ For this you will need to:
* Package a GeckoView [AAR](https://developer.android.com/studio/projects/android-library.html)
* Modify your Focus gradle configuration to use your custom GeckoView AAR.
# Setup build system
## Setup build system
Follow the [Build instructions](https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Build_Instructions/Simple_Firefox_for_Android_build) to setup a Firefox for Android build (ARM or x86).
@ -44,7 +46,7 @@ $ ls <your-output-directory>/gradle/build/mobile/android/geckoview/outputs/aar
geckoview-official-withGeckoBinaries-noMinApi-release.aar
```
# Point your Focus/Klar build to your AAR
## Point your Focus/Klar build to your AAR
In your Focus/Klar checkout open `app/build.gradle` (__not__ the build.gradle file in the root directory!) and locate the `repositories` block. This block defines where gradle will look for dependencies. Add the absolute path to your AAR as follows:

6
mobile/android/focus-android/docs/Feature-&-Issue-workflow.md
View File

@ -1,9 +1,11 @@
# High-Level Steps
# Feature & Issue workflow
## High-Level Steps
| Issue opened| ➡️ |Triaged| ➡️ |Ready in/for Backlog| ➡️ | Ready for UX | ➡️ | Ready for Eng| ➡️ |Eng done| ➡️ |Ready for review| ➡️ |Ready for QA| ➡️ |Done
|------|------|------|------|------|------|------|------|------|------|------|------|------|------|------|------|------
# Details
## Details
**Issue opened**
- Issue is created (by anybody)

2
mobile/android/focus-android/docs/Homescreen-Tips.md
View File

@ -1,3 +1,5 @@
# Homescreen Tips
## Homescreen Tips Explained 💡
Homescreen tips launched in Firefox Focus 7.0 in October 2018. They allow users to get more information about the product without having to research on their own or dig around in settings. Tips also enable users to _quickly_ access portions of the settings menu they may not know how to navigate otherwise. All tips have either a deep link to settings or a link to their corresponding SUMO article (if available).

2
mobile/android/focus-android/docs/Multisession-architecture.md
View File

@ -1,3 +1,5 @@
# Multisession Architecture
To support multiple simultaneous browsing sessions the architecture of Focus has been refactored to strictly separate sessions (and associated data) from the UI that displays this data.
Sessions are managed by a global `SessionManager` instance. UI components display data hold by `Session` objects.

2
mobile/android/focus-android/docs/Recommended-pre-push-hook.md
View File

@ -1,3 +1,5 @@
# Recommended pre-push hook
If you want to reduce your PR turn-around time, I'd recommend adding a
pre-push hook: this script will stop a push if the unit tests or linters
fail, finding the failures before it hits TaskCluster (which takes

10
mobile/android/focus-android/docs/Release-Process.md
View File

@ -1,4 +1,6 @@
### Creating a new Release Branch
# Release Process
## Creating a new Release Branch
1. Create a branch name with the format `releases_v[version]` (for example: `releases_v87.0`).
2. Pin the Android Components version to the final release version with the format `[version].0.0`.
@ -19,7 +21,7 @@
Automation should take over after you land your PR into the upstream `releases_v[version]` branch. You can verify by clicking on the branch in the UI, and looking for the green/yellow dot that will list links to the running build tasks.
### After the Beta release
## After the Beta release
Update the `versionName` from `build.gradle(Module:focus-android.app)` to the next Focus beta release version.This should be the `[version + 1]`.
For example, if the release cut was for `90`, we're looking to prepare the latest nightly for `91`.
@ -29,7 +31,7 @@ Automation should take over after you land your PR into the upstream `releases_v
|--------------------|--------------------|-----------------|
| build.gradle | 90 | 91 |
### Renew telemetry
## 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 `[release_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.
@ -47,7 +49,7 @@ After the Beta cut, another task is to renew/remove all soon to expire telemetry
- Why was the initial period of collection insufficient?
### Ask for Help
## Ask for Help
If you run into any problems, please ask any questions on Slack in #releaseduty-mobile.

12
mobile/android/focus-android/docs/Release-tracks.md
View File

@ -1,3 +1,5 @@
# Release tracks
![](https://raw.githubusercontent.com/mozilla-mobile/focus-android/master/app/src/main/res/mipmap-xxxhdpi/ic_launcher.png)
We have three public release tracks for Focus/Klar:
@ -9,7 +11,7 @@ We have three public release tracks for Focus/Klar:
* **Nightly**: We publish automated builds on this track every 24 hours. Those builds reflect the latest state of the repository (master). This track allows users to experience the newest Firefox Focus/Klar innovations in an unstable environment and provide feedback on features and performance to help determine what makes the final release. Nightly builds can be unstable and contain incomplete or defect features.
# Nightly
## Nightly
![](https://raw.githubusercontent.com/mozilla-mobile/focus-android/master/app/src/nightly/res/mipmap-xxxhdpi/ic_launcher.png)
@ -17,7 +19,7 @@ We have three public release tracks for Focus/Klar:
* Latest development state
* Can be unstable and contain incomplete or defect features
## How to sign up for Nightly
### How to sign up for Nightly
To get Focus Nightly on your device, follow these steps:
@ -28,13 +30,13 @@ To get Focus Nightly on your device, follow these steps:
Make sure you use the same Google Account for both steps.
# Beta
## Beta
![](https://raw.githubusercontent.com/mozilla-mobile/focus-android/master/app/src/focusBeta/res/mipmap-xxxhdpi/ic_launcher.png)
* Updates to the Beta track will typically be 1-2 times weekly.
## How to sign up for beta
### How to sign up for beta
To get Focus Beta on your device, follow these steps:
1) Visit https://groups.google.com/g/firefox-focus-pre-release and join the Google Group
2) After you have joined the group opt-in to receive Beta builds, again with the same Google account: https://play.google.com/apps/testing/org.mozilla.focus.beta
@ -43,7 +45,7 @@ To get Focus Beta on your device, follow these steps:
Make sure you use the same Google Account for both steps.
## Manual downloads
### Manual downloads
The latest Beta/Release builds can be downloaded manually from:
https://github.com/mozilla-mobile/focus-android/releases

2
mobile/android/focus-android/docs/Removing-strings.md
View File

@ -1,3 +1,5 @@
# Removing 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 by mistake, where strings are still needed. For this reason, we need a special process to remove them.

2
mobile/android/focus-android/docs/Sprint-Process.md
View File

@ -1,3 +1,5 @@
# Sprint Process
Focus follows a 2-week sprint cycle with 6-week milestone releases. Dot-releases with bugfixes are released every two weeks. Our upcoming train schedule is [here](https://wiki.mozilla.org/Mobile/Focus/Android/Train_Schedule).
## Issue naming and labels

48
mobile/android/focus-android/docs/Telemetry.md
View File

@ -1,15 +1,15 @@
# Telemetry
For clients that have "send anonymous usage data" enabled Focus sends a "core" ping and an "event" ping to Mozilla's telemetry service. Sending telemetry can be disabled in the app's settings. Builds of "Focus for Android" have telemetry enabled by default ("opt-out") while builds of "Klar for Android" have telemetry disabled by default.
# Core ping
## Core ping
Focus for Android creates and tries to send a "core" ping whenever the app goes to the background. This core ping uses the same format as Firefox for Android and is [documented on firefox-source-docs.mozilla.org](https://firefox-source-docs.mozilla.org/toolkit/components/telemetry/telemetry/data/core-ping.html).
# Event ping
## Event ping
In addition to the core ping an event ping for UI telemetry is generated and sent as soon as the app is sent to the background.
## Settings
### Settings
As part of the event ping the most recent state of the user's setting is sent (default values in **bold**):
@ -35,18 +35,18 @@ As part of the event ping the most recent state of the user's setting is sent (d
(***) An **empty string** value indicates "System Default" locale is selected.
## Events
### Events
The event ping contains a list of events ([see event format on readthedocs.io](https://firefox-source-docs.mozilla.org/toolkit/components/telemetry/telemetry/collection/events.html)) for the following actions:
### Sessions
#### Sessions
| Event | category | method | object | value |
|------------------------------------------|----------|------------|--------|--------|
| Start session (App is in the foreground) | action | foreground | app | |
| Stop session (App is in the background) | action | background | app | |
### Browsing
#### Browsing
| Event | category | method | object | value | extras. |
|----------------------------------------|----------|-----------------------|------------|--------|------------|
@ -61,7 +61,7 @@ The event ping contains a list of events ([see event format on readthedocs.io](h
| Autofill performed | action | click | autofill | | |
| Enable Search Suggestion from prompt | action | click | search_suggestion_prompt | true/false | |
### Custom Tabs
#### Custom Tabs
| Event | category | method | object | value | extra |
|---------------------------|----------|-------------------|----------------------|------------|------------|
@ -81,7 +81,7 @@ The event ping contains a list of events ([see event format on readthedocs.io](h
}
```
### Context Menu
#### Context Menu
| Event | category | method | object | value |
|----------------------------------------|----------|--------|---------------------|------------|
@ -98,7 +98,7 @@ The event ping contains a list of events ([see event format on readthedocs.io](h
### Erasing session
#### Erasing session
| Event | category | method | object | value | extras |
|----------------------------------------|----------|-------------|---------------------|------------|---------|
@ -120,7 +120,7 @@ The event ping contains a list of events ([see event format on readthedocs.io](h
}
```
### Menu
#### Menu
| Event | category | method | object | value | extras |
|---------------------------------------------|----------|----------|-----------------|--------------|----------|
@ -145,7 +145,7 @@ The event ping contains a list of events ([see event format on readthedocs.io](h
}
```
### Notification
#### Notification
| Event | category | method | object | value | extras |
|---------------------------------------|----------|----------|---------------------|------------|---------|
@ -161,7 +161,7 @@ The event ping contains a list of events ([see event format on readthedocs.io](h
"total": "5" // Total number of open tabs
}
```
### Page Load Time Histogram
#### Page Load Time Histogram
| Event | category | method | object | extras|
@ -176,7 +176,7 @@ The event ping contains a list of events ([see event format on readthedocs.io](h
{"19900", "4"}
```
### URI Count
#### URI Count
| Event | category | method | object | extra |
|---------------------------------------------|----------|----------|---------------------|-----------------|
@ -184,21 +184,21 @@ The event ping contains a list of events ([see event format on readthedocs.io](h
| The count of the unique domains visited in a subsession, after the session has been restored. Subdomains under eTLD are aggregated after the first level (i.e. test.example.com and other.example.com are only counted once). This does not include background page requests and domains from embedded pages or private browsing. | action | open | browser | `{"unique_domains_count": num }` |
### Downloads
#### Downloads
| Event | category | method | object | value |
|---------------------------------------------|----------|----------|---------------------|-----------------|
| Clicked "Download" | action | click | download_dialog | download |
| Clicked "Cancel" | action | click | download_dialog | cancel |
### Open Focus From Icon
#### Open Focus From Icon
| Event | category | method | object | value |
|---------------------------------------------|----------|----------|---------------------|-----------------|
| Launched Focus From Icon | action | click | app_icon | open |
| Resume Focus From Icon | action | click | app_icon | resume |
### Add to Home screen
#### Add to Home screen
| Event | category | method | object | value |
|-----------------------------------------|----------|----------|--------------------------|-------------------|
@ -206,14 +206,14 @@ The event ping contains a list of events ([see event format on readthedocs.io](h
| Clicked "Cancel" in dialog | action | click | add_to_homescreen_dialog | cancel |
| Open Focus from Home screen shortcut | action | click | homescreen_shortcut | open |
### Share to Focus Event
#### Share to Focus Event
| Event | category | method | object | value |
|---------------------------------------------|----------|----------|---------------------|-----------------|
| Shared URL to Focus | action | share_intent | app | url |
| Shared Search Terms to Focus | action | share_intent | app | search |
### Settings
#### Settings
| Event | category | method | object | value | extras |
|--------------------------------|----------|----------|-------------------------|-------|--------------------------
@ -251,7 +251,7 @@ The event ping contains a list of events ([see event format on readthedocs.io](h
(*) `bool` true if successfully saved, false if validation error
### Firstrun
#### Firstrun
| Event | category | method | object | value |
|---------------------------------------------|----------|----------|---------------------|--------------|
@ -261,7 +261,7 @@ The event ping contains a list of events ([see event format on readthedocs.io](h
(*) Page numbers start at 0. Initially when the firstrun tour is shown an event for the first page (0) is fired.
### Multitasking / Tabs
#### Multitasking / Tabs
| Event | category | method | object | value | extras |
|--------------------------------------------|----------|----------|---------------------|-------|---------|
@ -280,7 +280,7 @@ The event ping contains a list of events ([see event format on readthedocs.io](h
}
```
### Homescreen Tips
#### Homescreen Tips
| Event | category | method | object | value |
|------------------------------------------|----------|------------|--------|--------|
@ -303,7 +303,7 @@ The event ping contains a list of events ([see event format on readthedocs.io](h
| Survey (fr) tip displayed | action | show | tip | survey_tip_fr | |
| Survey (fr) tip tapped | action | click | tip | survey_tip_fr | |
### SSL Errors
#### SSL Errors
| Event | category | method | object | extras |
|--------------------------------------------|----------|----------|---------|---------|
@ -328,13 +328,13 @@ The event ping contains a list of events ([see event format on readthedocs.io](h
|SSL_INVALID |
|Undefined SSL Error |
## Limits
### Limits
* An event ping will contain up to but no more than 500 events
* No more than 40 pings per type (core/event) are stored on disk for upload at a later time
* No more than 100 pings are sent per day
# Implementation notes
## Implementation notes
* Event pings are generated (and stored on disk) whenever the onStop() callback of the main activity is triggered. This happens whenever the main screen of the app is no longer visible (The app is in the background or another screen is displayed on top of the app).

2
mobile/android/focus-android/docs/UI-Test.md
View File

@ -1,3 +1,5 @@
# UI Test
To run automated tests on firefox focus, you will need a few things to get started.
1. Working installation of git and a local clone of the this Focus repository. You can do:

28
mobile/android/focus-android/docs/index.rst Normal file
View File

@ -0,0 +1,28 @@
=================================
Focus for Android
=================================
Specific documentation on a few topics is available at:
.. toctree::
:maxdepth: 1
Adjust Usage <Adjust-Usage.md>
Architecture Decisions <Architecture-Decisions.md>
Battery Debugging <Battery-Debugging.md>
Content blocking <Content-blocking.md>
Crash Reporting with Sentry <Crash-Reporting-with-Sentry.md>
Development Custom GeckoView <Development-Custom-GeckoView.md>
Feature & Issue workflow <Feature-&-Issue-workflow.md>
Running GeckoView in a debug environment <GeckoView-(In-Progress).md>
Home <Home.md>
Homescreen Tips <Homescreen-Tips.md>
Multisession architecture <Multisession-architecture.md>
Recommended pre-push hook <Recommended-pre-push-hook.md>
Release Process <Release-Process.md>
Release tracks <Release-tracks.md>
Removing strings<Removing-strings.md>
Sprint Process <Sprint-Process.md>
Telemetry <Telemetry.md>
UI Test <UI-Test.md>
l10n Screenshot Generation <l10n-Screenshot-Generation.md>

2
mobile/android/focus-android/docs/l10n-Screenshot-Generation.md
View File

@ -1,3 +1,5 @@
# l10n Screenshot Generation
This wiki describes the steps to generate l10n screenshots on a device.
## Prerequisites

1
mobile/android/moz.build
View File

@ -86,6 +86,7 @@ TEST_HARNESS_FILES.testing.mochitest.tests.junit += [
SPHINX_TREES["/mobile/android"] = "docs"
SPHINX_TREES["/mobile/android/fenix"] = "fenix/docs"
SPHINX_TREES["/mobile/android/focus-android"] = "focus-android/docs"
with Files("docs/**"):
SCHEDULES.exclusive = ["docs"]