1 files changed, 232 insertions, 0 deletions
diff --git a/mobile/android/docs/geckoview/design/breaking-changes.rst b/mobile/android/docs/geckoview/design/breaking-changes.rst
new file mode 100644
index 0000000000..8838a225fa
--- /dev/null
+++ b/mobile/android/docs/geckoview/design/breaking-changes.rst
@@ -0,0 +1,232 @@
+Breaking changes in GeckoView
+=============================
+
+Agi sferro <agi@sferro.dev>
+
+Abstract
+--------
+
+This document describes the reasoning behind the GeckoView deprecation policy,
+where we are today and where we want to be in the future.
+
+Background
+----------
+
+The following sections illustrate how breaking changes are expensive and
+frustrating as a consumer of GeckoView, as a Gecko engineer and as an external
+consumer, how they take away time from the Fenix team and reduce the average
+testing time on Nightly up to 30%. And finally, how breaking changes negate the
+very advantages that brought us to the current modularized architecture.
+
+Introduction
+------------
+
+GeckoView is a library that provides consumers access to Gecko and is the main
+way through which Gecko is consumed on Mozilla’s Android products.
+
+GeckoView provides Nightly, Beta and Release channels which update with the
+same cadence as Firefox Desktop does.
+
+Firefox for Android (code name Fenix) is developed on a standalone repository
+on GitHub and uses GeckoView through Android Components (AC for short), an
+Android library also developed on its own standalone repository.
+
+Fenix also provides Nightly, Beta and Release updates that mirror GeckoView and
+Firefox Desktop’s.
+
+Testing days
+------------
+
+All Firefox Gecko-based products release a new major version every 4 weeks.
+Which means that, on average, a commit that lands on a random day during the
+release cycle gets 2 weeks of testing time on the Nightly user base.
+
+We try to increase the average testing time on Nightly by having a few “soft”
+code-freeze days before each Merge day where engineers are not supposed to push
+risky changes, but there’s no enforcement and it’s left to each engineer to
+decide whether their change is risky or not.
+
+Each day where the Nightly build is delayed, every change contained in the
+current Nightly cycle gets 7% (1 out of 14 days) on average less testing that
+it normally would during a build. That is assuming that a problem gets
+immediately reported and the report is immediately referred to the right
+Engineering team.
+
+Assuming a 4 days report delay, each day where the Nightly build is delayed,
+due to reasons such as breaking changes, reduces the average testing time by
+10%.
+
+Nightly update
+--------------
+
+Fenix Nightly consumes GeckoView indirectly through Android Components. Each
+day, an automated script makes a change in Fenix’s codebase to update AC’s
+version. This change is then submitted to Fenix’s CI and, if all tests pass, is
+merged to the codebase automatically.
+
+A new Fenix Nightly build is then generated and automatically published to
+Google’s Play Store, from where it gets distributed to all Nightly users on
+Android.
+
+Android Components has a similar automated process which publishes new versions
+every day, picking up the new GeckoView nightly build.
+
+The update process fails from time to time. The cause of the failure largely
+falls in one of the following three buckets.
+
+- An intermittent test failure
+- A bug introduced in the latest AC or GeckoView update which causes a test to
+  fail
+- A backward incompatible change has been made in AC or GeckoView that breaks
+  the build.
+
+The current mitigation for 1 is to disable or fix tests that fail
+intermittently, similarly to what happens in mozilla-central.
+
+2 and 3 are problems unique to Fenix and AC (as compared to Firefox Desktop)
+and are a direct consequence of the multi-package infrastructure of Fenix.
+
+Build breakages
+---------------
+
+When the automated Nightly update fails, an engineer on the Fenix team needs to
+manually intervene to unblock the build.
+
+The need for a manual intervention automatically adds a day of Nightly build
+delay when the failure occurs outside of business hours, and 2 or 3 days of
+delay when the failure happens on a Friday night.
+
+Therefore, even assuming that a build breakage takes no time to fix, the
+average testing time is reduced by 7-30% for each build breakage that occurs.
+
+In the case where the breakage takes a few days or more to fix, the average
+testing time can be reduced to as much as half of what it would be on a
+breakage-free Nightly cycle.
+
+Build breakages put undue burden on the Fenix team, who has to jump on the
+breakage and has to drop their current work to avoid losing additional testing
+days.
+
+Reducing breakages
+------------------
+
+Breakages caused by upstream teams like GeckoView can be divided into 2 groups:
+
+- Behavior changes that cause test failures downstream
+- Breaking changes in the API that cause the build to fail.
+
+To reduce breakages from group 1, the GeckoView team maintains an extensive set
+of integration tests that operate solely on the GeckoView API, and therefore
+rarely break because of refactoring.
+
+For group 2, the GeckoView team instituted a deprecation policy which requires
+each backward-incompatible change to keep the old code for 3 releases, allowing
+downstream consumers, like Fenix, time to migrate asynchronously to the new
+code without breaking the build.
+
+Functional testing and prototyping
+----------------------------------
+
+GeckoView offers a test browser app called GeckoViewExample (or GVE) that is
+developed in-tree and thus always available to test local changes.
+
+GVE is the main testing vehicle for Gecko and GeckoView engineers that want to
+develop new code, however, there frequently are issues or new features that
+cannot be tested on GVE and need to be tested directly on Fenix.
+
+To test new code in Fenix, the build system offers an easy way to swap
+locally-build GeckoView in Fenix.
+
+The process of testing new Gecko code in Fenix needs to be straightforward, as
+it’s often used by platform engineers that are unfamiliar with Android and
+Fenix itself, and are not likely to retain knowledge from running code on
+Android and would likely need help to do so from the GeckoView or Fenix team.
+
+Side-effects of build breakages
+-------------------------------
+
+When a breakage lands in mozilla-central and until the breakage is fixed in the
+Fenix codebase, a locally built GeckoView is not compatible with the
+most-recent tip of Fenix.
+
+This can be confusing to an engineer that is unfamiliar to Fenix, and can cause
+frustration and time lost trying to figure out why upstream code, without
+modifications, fails to compile.
+
+Beyond confusion, an incompatibility on the GeckoView/Fenix combined history
+negates the primary advantage of building Fenix in a separate package:
+decoupling Gecko from the Android front-end.
+
+Building older versions from source is also harder, as the set of version
+couples (GeckoView, Fenix) that are compatible with each other is not
+explicitly documented anywhere.
+
+External consumers
+------------------
+
+For apps interested in building a browser for Android, GeckoView provides the
+unique combination of being a modern Web engine with a relatively stable API.
+
+For comparison, alternatives to GeckoView include:
+
+- WebView, Android’s way of embedding web pages on Android apps. WebView has
+  has several drawbacks for browser developers, including:
+
+  - having a limited API for building browsers, as it does not expose modern
+    Web features or browser-specific APIs like bookmarks, passwords, etc;
+  - not allowing developers to control the underlying Chromium version. WebView
+    users will get whatever version of WebView is installed on the device.
+  - On the other hand, using WebView has the advantage of providing a smaller
+    download package, as the bulk of the engine is already installed on the
+    device.
+
+- Fork Chromium, which has the drawback of either having to rewrite the entire
+  browser front-end or locally patching the Chrome front-end, which involves
+  frequent changes and updates to be on top of. Using Chromium has the advantage
+  of providing the most stable, performant and compatible Web Engine on the
+  market.
+
+If the cost of updating GeckoView becomes high enough because of frequent API
+changes, the advantage of using GeckoView is negated.
+
+Prior Art
+---------
+
+Many public libraries offer a deprecation policy similar or better than
+GeckoView. For example, Android APIs need to be deprecated for a few releases
+before being considered for removal, and completely removed only in exceptional
+cases. Google products’ deprecated APIs are supported for a year before being
+removed. Ebay requires deprecating an API before removal.
+
+Status quo
+----------
+
+Making backward-incompatible changes to the GeckoView API is currently heavily
+discouraged and requires approval by the GeckoView team.
+
+We do, however, have breaking changes from time to time. The last breaking
+change was in June 2021, a refactor of the permission API which we didn’t think
+was worth executing in a backward compatible way. Before that, the last
+breaking change was in September 2020.
+
+Tracking breaking changes
+-------------------------
+
+Internally, GeckoView tracks the API using apilint. Each change that touches
+the API requires an additional GeckoView peer to review the patch and a
+description of the change in the changelog.
+
+Apilint also tracks deprecated APIs and enforces their removal, so that old,
+deprecated APIs don’t linger in the codebase for longer than necessary.
+
+The future
+----------
+
+The ideal end state for GeckoView would be to not have any more backward
+incompatible changes. Our experience is that supporting the old APIs for a
+limited time is a small overhead in our development and that the benefits from
+having a backward compatible API greatly outweigh the cost.
+
+We cannot, however, predict all future needs of GeckoView and Firefox as a
+whole, so we cannot exclude the possibility of having new breaking changes
+going forward.