Compatibility/System Addon/Override Policies and Workflows: Difference between revisions

← Older edit

Compatibility/System Addon/Override Policies and Workflows (view source)

Revision as of 20:34, 13 June 2023

608 bytes removed , 13 June 2023

added automated testing section/link

Twisniewski

27

edits

@@ Line 1: / Line 1: @@
-== Preamble ==
+= Preamble =
 If important sites are broken in Firefox, getting them fixed is our highest priority (even if by the user agent intervening on behalf of the user). However, there's a balance to be struck: we do not have the bandwidth to fix the entire web, and patching certain problem may disincentivize developers from fixing their bugs.
@@ Line 5: / Line 5: @@
 As a guiding principle, if deploying a site patch or override would dramatically improve user experience or fix a top site it should be seriously considered. At the same time, we make efforts to remove the override as soon as possible, working with the site developers where possible.
-== Override or not? ==
+Consult [[Compatibility/Interventions_Releases|Intervention Releases]] for more information on the process of shipping interventions.
+= To Override or not? =
 Our goal is to fix top sites, or sites that will have the most impact for Firefox users.
@@ Line 13: / Line 15: @@
 * Trending sites should also be considered, even when they don't rank highly in global usage metrics.
-== Checklist for shipping a site patch  ==
+= Types of Interventions =
-The requirements to ship a site patch follow:
-# There should be an issue on GitHub or Bugzilla. In that bug, diagnosis needs to be done first to validate that the issue is indeed caused by a user agent detection (if you plan on adding an UA override), or can be fixed with injecting JS or CSS.
-# A [https://bugzilla.mozilla.org/enter_bug.cgi?product=Web%20Compatibility%20Tools&component=Go%20Faster Web Compatibility Tools::Go Faster] Bugzilla bug must be opened, with the See Also field linking to the original Bugzilla or GitHub issue that contains the diagnosis and justification for a site patch.
-# A patch is written and pull request opened against the [https://github.com/mozilla/webcompat-addon GitHub repo], seeking review from a [https://github.com/orgs/mozilla/teams/webcompat/members webcompat team member].
-# Once the site patch is validated locally and given an r+, the PR should get merged.
-# A patch should be generated against Mozilla Central in order to release a new version of the Go Faster addon, following [https://github.com/mozilla/webcompat-addon#exporting-the-sources-to-mozilla-central these instructions], including a minor version bump.
-# The patch should be attached to the bug in Step 2 and a [[Modules/All#Firefox|Firefox module peer]] must give an r+ for landing.
-# A signed XPI built from the r+ patch for deploying should be attached to the bug in Step 2. See the [[Firefox/Go_Faster/System_Add-ons/Process#QA_and_Code_Review|Go Faster Process Document]] for further info.
-# A [https://mana.mozilla.org/wiki/display/PI/PI+Request PI Request] should be sent linking to the XPI for testing against the site being patched.
-# An intent to ship email must be sent and RelMan approval obtained, per the [[Firefox/Go_Faster/System_Add-ons/Process#Intent_to_Ship_and_RelMan_Approval|Go Faster Process]].
-== Types of Overrides ==
+== User Agent overrides ==
-=== User Agent overrides ===
+=== Designing the override ===
-==== Designing the override ====
 * Since we are able to set a very specific scope for overrides, we aim to limit the scope of overrides as much as possible. If only a specific site in a specific subdirectory is affected, it's much better to override just that segment instead of overriding the UA for the entire site.
 * We try to touch the user agent as little as possible. If adding a segment like "mobile" or "iPhone" solves an issue, this is should be preferred over replacing the entire UA. That way, Firefox still might be recognized by the sites statistics.
-==== Technical details ====
+=== Technical details ===
 User agent overrides are defined within [https://github.com/mozilla/webcompat-addon/blob/master/src/data/ua_overrides.js src/data/ua_overrides.js] of the addon sources. In this file, you will only find an array containing all active user agent overrides. Each object can have three attributes:
@@ Line 70: / Line 58: @@
 </syntaxhighlight>
-=== CSS Injections ===
+== CSS Injections ==
-==== Designing the injection ====
+=== Designing the injection ===
 As with user agent overrides, CSS injections should be designed to use as little code as possible. Due to the nature of these overrides, it is hard to provide exact guidelines.
@@ Line 78: / Line 66: @@
 Injected CSS files will be in the first place of the cascading chain, so be careful to use selectors with a high specificity, or use the ''!important'' keyword.
-==== Technical details ====
+=== Technical details ===
 CSS injections are defined within individual files within the [https://github.com/mozilla/webcompat-addon/blob/master/src/webextension/injections/css/ src/webextension/injections/css/] directory of the addon sources. In this folder, you will find a collection of files, one file per override or injection. For easier cross-reference, please stick to the ''bugNNNNN-short-description.css'' file name schema.
@@ Line 84: / Line 72: @@
 In addition, the injection file has to be registered in the constant array located at the top of [https://github.com/mozilla/webcompat-addon/blob/master/src/webextension/background.js#L7 src/webextension/background.js]. Details on available parameters can be found [https://developer.mozilla.org/en-US/Add-ons/WebExtensions/manifest.json/content_scripts in the MDN web docs].
-=== JS Injections ===
+== JS Injections ==
-==== Designing the injection ====
+=== Designing the injection ===
 As with user agent overrides, JS injections should be designed to use as little code as possible. Due to the nature of these overrides, it is hard to provide exact guidelines.
@@ Line 102: / Line 90: @@
 </syntaxhighlight>
-==== Technical details ====
+=== Technical details ===
 JS injections are defined within individual files within the [https://github.com/mozilla/webcompat-addon/blob/master/src/webextension/injections/js/ src/webextension/injections/js/] directory of the addon sources. In this folder, you will find a collection of files, one file per override or injection. For easier cross-reference, please stick to the ''bugNNNNN-short-description.js'' file name schema.
@@ Line 108: / Line 96: @@
 In addition, the injection file has to be registered in the array located in [https://github.com/mozilla/webcompat-addon/blob/master/src/data/injections.js rc/data/injections.js]. Details on available parameters can be found [https://developer.mozilla.org/en-US/Add-ons/WebExtensions/manifest.json/content_scripts in the MDN web docs].
-== Open points for further discussion ==
+=== Using "custom functions" for more complex overrides
+Some injections may require additional logic inside the WebExtension to make them work. An example of this could be a custom blocking ''browser.webRequest.onBeforeRequest'' handler to detect and alter the usage of a popular JavaScript library. To use customized logic, define a ''customFunc'' in your injection definition:
+<syntaxhighlight lang="js">
+{
+  id: "bug1551672",
+  platform: "android",
+  domain: "Sites using PDK 5 video",
+  bug: "1551672",
+  data: {
+    urls: ["https://*/*/tpPdk.js", "https://*/*/pdk/js/*/*.js"],
+    types: ["script"],
+  },
+  customFunc: "pdk5fix",
+}
+</syntaxhighlight>
+Then, head to ''src/lib/custom_functions.js'' and make sure to define the function you just named. Suppose you need additional logic for clearing up when disabling the intervention, for example, to unregister a handler. In that case, you can define a second function with the ''Disable'' suffix, ''pdk5fixDisable'' in this example.
+Custom functions are executed within the background script and have full permissions to do anything that a WebExtension background script can do.
+= Automated Testing =
+See https://wiki.mozilla.org/Compatibility/System_Addon/Automated_Testing
+= Open points for further discussion =
 Some cases might never be added to this decision guide, but discussed with the team on the individual case:
 * Should we override/inject if a site adds a "Your browser is not supported" note? What if the warning is really annoying or even blocking the site, what if it's just a note?
-* How do we make sure that our override is indeed working? What do we need to test?
 * Do we override websites that require a login? How can we ensure that we don't break the site with overriding the user agent or injecting code?
 [[Category:Web Compatibility]]