Compatibility/Go Faster Addon/User Agent Override Policy
There is no fixed guideline or a checklist on when to add a user agent 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 UA 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, user agent 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.
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.
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 the UA 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?
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.
- 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 a user agent detection issue is confirmed, there should be some investigations on the least invasive UA override possible.
- When the "UA override MVP" was found, a pull request against the GitHub repo should be opened.
- 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?]
- If both the override and the test are validated, the PR should get merged.
- 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.]