Compatibility/System Addon/Override Policies and Workflows

Preamble

There is no fixed guideline or a checklist on when to add an override or not. Instead, this project is rather dynamic and depends on the individual case. This document provides some help in making that decision.

In general, decisions are made rather fast and we are able to roll out new overrides to the users quickly. [ToDo: Who makes the decision? I feel like more than one person should be involved, but I am not sure who. Maybe a quick discussion on the webcompat bug to see if anyone has objections?]

The user is more important than the web and the web is more important than browser vendors. If sites are broken, getting them working again should have the highest priority. On the other hand, if we add overrides every time something breaks, we might not be able to convince the site developers to roll out a fix since the site will be working in their tests.

Override or not?

We try to make this decision mainly based on the sites popularity. There is no point in adding an override for a small site with a high likelihood our suggestions will never be implemented. Ultimately, all overrides should be a temporary measure, not a long-term fix.

• If a site is very popular, a lot of users may be affected by the bug and we should put an override in place before going into outreach (or, even better, do both at the same time) to reduce the user impact.
• We have no fixed threshold on the sites rank that qualifies for an override. However, we might set a soft limit in the future if we have some experience.
• It's important to consider a site's popularity on a by-country level, not a global level. Some sites may be very popular in one market, but completely irrelevant to others. While this particular case might not have a huge global impact, losing users from one market can be painful.
• Some sites may be very popular for a short period of time, but not popular at all in a global statistic. Examples are marketing sites for events, projects from raising startups, ... It's important to consider those as well.

Generic Process of adding an override

While the code of our Go Faster Addon is hosted on GitHub, additional steps need to be done for adding an override.

1. 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.
2. If a user agent detection issue is confirmed, there should be some investigations on the least invasive UA override possible.
3. When the "minimum viable product" was found, a pull request against the GitHub repo should be opened.
4. At the same time, a test case for validating the need of this override should be written. [Note: this is an ongoing project and there will be more details on that in the future.] That way, we will get notified if the site got fixed and the user agent is no longer needed. [ToDo: will our testing framework also include a time based notification so we don't forget that we need to remove old overrides?]
5. If both the override and the test are validated, the PR should get merged.
6. If the PR is merged, a new version of the Go Faster addon should be released and rolled out to the users. [ToDo: clarify how.]

Types of Overrides

User Agent overrides

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

User agent overrides are defined within src/content/data/ua_overrides.jsm 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:

• baseDomain, required: The base domain that further checks and user agents override are applied to. This does not include subdomains.
• applications: Array of applications this override is valid in. Defaults to ["firefox"], can be one or more of:
  • firefox: Firefox Desktop (regardless of the operating system)
  • fennec: Firefox for Android
• uriMatcher: Function that gets the requested URI passed in the first argument and needs to return boolean whether or not the override should be applied. If not provided, the user agent override will be applied every time.
• uaTransformer, required: Function that gets the original Firefox user agent passed as its first argument and needs to return a string that will be used as the the user agent for this URI.

Examples

Gets applied for all requests to mozilla.org and subdomains made on Firefox Desktop:

  {
    baseDomain: "mozilla.org",
    uriMatcher: (uri) => uri.includes("/app/"),
    uaTransformer: (originalUA) => `Ohai Mozilla, it's me, ${originalUA}`
  }

Applies to *.example.com/app/* on Firefox for Android:

  {
    baseDomain: "example.com",
    applications: ["fennec"],
    uriMatcher: (uri) => uri.includes("/app/"),
    uaTransformer: (originalUA) => originalUA.replace("Firefox", "Otherfox")
  }

CSS Injections

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.

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

CSS injections are defined within individual files within the 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.

In addition, the injection file has to be registered in the manifest file located at src/webextension/manifest.json. Details on available parameters can be found in the MDN web docs.

JS Injections

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.

The injected JS will be executed in its own context per default, check the MDN web docs for details. If it is required to run JS in the websites context, JS code can be wrapped inside an eval call:

window.eval(`(function() {  // used to require window.wrappedJSObject.eval
  /* your code here */
}());`);

Technical details

JS injections are defined within individual files within the 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.

In addition, the injection file has to be registered in the manifest file located at src/webextension/manifest.json. Details on available parameters can be found in the MDN web docs.

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?