breaking-changes.rst (6683B)
1 Breaking changes in GeckoView 2 ============================= 3 4 Agi sferro <agi@sferro.dev> 5 6 Abstract 7 -------- 8 9 This document describes the reasoning behind the GeckoView deprecation policy, 10 where we are today and where we want to be in the future. 11 12 Background 13 ---------- 14 15 The following sections illustrate how breaking changes are expensive and 16 frustrating as a consumer of GeckoView, as a Gecko engineer and as an external 17 consumer, how they take away time from the Fenix team. And finally, how 18 breaking changes negate the very advantages that brought us to the current 19 modularized architecture. 20 21 Introduction 22 ------------ 23 24 GeckoView is a library that provides consumers access to Gecko and is the main 25 way through which Gecko is consumed on Mozilla’s Android products. 26 27 GeckoView provides Nightly, Beta and Release channels which update with the 28 same cadence as Firefox Desktop does. 29 30 Firefox for Android (code name Fenix) uses GeckoView through Android Components 31 (AC for short), an Android library. 32 33 Fenix also provides Nightly, Beta and Release updates that mirror GeckoView and 34 Firefox Desktop’s. 35 36 Testing days 37 ------------ 38 39 All Firefox Gecko-based products release a new major version every 4 weeks. 40 Which means that, on average, a commit that lands on a random day during the 41 release cycle gets 2 weeks of testing time on the Nightly user base. 42 43 We try to increase the average testing time on Nightly by having a few “soft” 44 code-freeze days before each Merge day where engineers are not supposed to push 45 risky changes, but there’s no enforcement and it’s left to each engineer to 46 decide whether their change is risky or not. 47 48 Each day where the Nightly build is delayed, every change contained in the 49 current Nightly cycle gets 7% (1 out of 14 days) on average less testing that 50 it normally would during a build. That is assuming that a problem gets 51 immediately reported and the report is immediately referred to the right 52 Engineering team. 53 54 Assuming a 4 days report delay, each day where the Nightly build is delayed, 55 due to reasons such as breaking changes, reduces the average testing time by 56 10%. 57 58 Reducing breakages 59 ------------------ 60 61 Breakages caused by upstream teams like GeckoView can be divided into 2 groups: 62 63 - Behavior changes that cause test failures downstream 64 - Breaking changes in the API that cause the build to fail. 65 66 To reduce breakages from group 1, the GeckoView team maintains an extensive set 67 of integration tests that operate solely on the GeckoView API, and therefore 68 rarely break because of refactoring. 69 70 For group 2, the GeckoView team instituted a deprecation policy which requires 71 each backward-incompatible change to keep the old code for 3 releases, allowing 72 downstream consumers, like Fenix, time to migrate asynchronously to the new 73 code without breaking the build. 74 75 Functional testing and prototyping 76 ---------------------------------- 77 78 GeckoView offers a test browser app called GeckoViewExample (or GVE) that is 79 developed in-tree and thus always available to test local changes. 80 81 GVE is the main testing vehicle for Gecko and GeckoView engineers that want to 82 develop new code, however, there frequently are issues or new features that 83 cannot be tested on GVE and need to be tested directly on Fenix. 84 85 To test new code in Fenix, the build system offers an easy way to swap 86 locally-build GeckoView in Fenix. 87 88 The process of testing new Gecko code in Fenix needs to be straightforward, as 89 it’s often used by platform engineers that are unfamiliar with Android and 90 Fenix itself, and are not likely to retain knowledge from running code on 91 Android and would likely need help to do so from the GeckoView or Fenix team. 92 93 External consumers 94 ------------------ 95 96 For apps interested in building a browser for Android, GeckoView provides the 97 unique combination of being a modern Web engine with a relatively stable API. 98 99 For comparison, alternatives to GeckoView include: 100 101 - WebView, Android’s way of embedding web pages on Android apps. WebView has 102 has several drawbacks for browser developers, including: 103 104 - having a limited API for building browsers, as it does not expose modern 105 Web features or browser-specific APIs like bookmarks, passwords, etc; 106 - not allowing developers to control the underlying Chromium version. WebView 107 users will get whatever version of WebView is installed on the device. 108 - On the other hand, using WebView has the advantage of providing a smaller 109 download package, as the bulk of the engine is already installed on the 110 device. 111 112 - Fork Chromium, which has the drawback of either having to rewrite the entire 113 browser front-end or locally patching the Chrome front-end, which involves 114 frequent changes and updates to be on top of. Using Chromium has the advantage 115 of providing the most stable, performant and compatible Web Engine on the 116 market. 117 118 If the cost of updating GeckoView becomes high enough because of frequent API 119 changes, the advantage of using GeckoView is negated. 120 121 Prior Art 122 --------- 123 124 Many public libraries offer a deprecation policy similar or better than 125 GeckoView. For example, Android APIs need to be deprecated for a few releases 126 before being considered for removal, and completely removed only in exceptional 127 cases. Google products’ deprecated APIs are supported for a year before being 128 removed. Ebay requires deprecating an API before removal. 129 130 Status quo 131 ---------- 132 133 Making backward-incompatible changes to the GeckoView API is currently heavily 134 discouraged and requires approval by the GeckoView team. 135 136 We do, however, have breaking changes from time to time. The last breaking 137 change was in June 2021, a refactor of the permission API which we didn’t think 138 was worth executing in a backward compatible way. Before that, the last 139 breaking change was in September 2020. 140 141 Tracking breaking changes 142 ------------------------- 143 144 Internally, GeckoView tracks the API using apilint. Each change that touches 145 the API requires an additional GeckoView peer to review the patch and a 146 description of the change in the changelog. 147 148 Apilint also tracks deprecated APIs and enforces their removal, so that old, 149 deprecated APIs don’t linger in the codebase for longer than necessary. 150 151 The future 152 ---------- 153 154 The ideal end state for GeckoView would be to not have any more backward 155 incompatible changes. Our experience is that supporting the old APIs for a 156 limited time is a small overhead in our development and that the benefits from 157 having a backward compatible API greatly outweigh the cost. 158 159 We cannot, however, predict all future needs of GeckoView and Firefox as a 160 whole, so we cannot exclude the possibility of having new breaking changes 161 going forward.