WebExtensions/policy

This document outlines the policy surrounding the WebExtensions API and aims to provide guidance on what makes a good API. When a change to the WebExtensions API is proposed, this document should be consulted to determine if the change makes sense. Changes can include adding a new API, changing an existing API, and/or removing (deprecating) an API. This process is necessary if you intend to make "substantial" changes to the WebExtensions API. What constitutes a "substantial" change evolves based on community norms and varies depending on what part of the ecosystem you are proposing to change, but may include the following:

• Adding an API to expose new areas of browser control or customization
• Any semantic or syntactic change to an existing API that is not a bug fix
• Deprecating and/or removing existing an API

Not all changes to the WebExtensions API require this level of review. Many can be handled via the existing bugzilla triage processes. For example:

• Reorganizing, refactoring, or cleaning up an API without impact to its meaning
• Changes that strictly improve objective, numerical quality criteria (warning removal, speedup, better platform coverage, more parallelism, trap more errors, etc.)
• Changes likely to be noticed only by other developers of WebExtensions API, invisible to actual users of the WebExtensions API.

This document only helps answer the question of should something be part of the WebExtensions API. It does not cover the actual process of how something becomes part of the WebExtensions API.

The process of maintaining and improving the WebExtensions API is a joint exploration of design space and tradeoffs, and requires consensus-building. The process is at its best when all participants recognize that people have differences of opinion and that every design or implementation choice carries a trade-off. There is seldom one right answer.

People wishing to participate in the definition and development of the WebExtensions API, including both Mozilla staff and community members, are expected to adhere to the Mozilla Community Participation Guidelines. These guidelines offer advice on how to participate in a healthy and constructive manner and also include language about harassment and marginalized groups.

When evaluating changes or additions to the WebExtensions API, the following items will be considered:

I. Mozilla Mission

Our mission is to ensure the Internet is a global public resource, open and accessible to all. An Internet that truly puts people first, where individuals can shape their own experience and are empowered, safe and independent.

The Mozilla mission statement lies at the core of everything that we do, with the values and beliefs that go into the mission outlined in the Mozilla Manifesto. Any change to the WebExtensions API must, above all else, be in line with the mission. This does not mean every new API must directly or overtly support the goals of the mission, but it absolutely cannot run counter to it. Any new API that could, for example, decrease accessibility is unlikely to be approved.

• Does this API align with the Mozilla mission?

II. Security / Privacy

Any API that could weaken a user’s security or compromise their privacy will be examined with extreme scrutiny. It often helps to imagine what nefarious things could be done with the API since, unfortunately, that is likely to happen. It is important to not just consider the proposed API in isolation, but also how the proposed API might be used in conjunction with other API to circumvent security and privacy controls.

In addition to direct security and privacy implications of the API itself, user consent is also an important consideration. API that can be used to alter web content or change browser behavior, for example, must receive explicit permission from the user. And once permission is granted, the user must be able to determine that an extension using the API is controlling some aspect of their browser. In short, the user must always be fully aware of and in control of their browsing experience, with the ability to easily revert back to default behavior.

• What are the security / privacy implications of this API?
• What permissions will the user need to explicitly grant to use this API?
• Are new security / privacy permissions needed?
• Will the user know if an API has taken control of a browser feature?

III. User Impact

An API that appeals to a broad audience is always preferred, although certain API that can demonstrate they empower a narrow but important set of extensions will also be considered. In all cases, though, the API needs to bring value to users of the browser.

The best way to judge whether an API has value is to understand the impact that the API would have on the market. In the ideal situation, you would have numbers to back up any assertion in this area. For example, knowing how many different developers requested an API is good data. Sometimes, however, the impact can only be subjectively estimated to determine if the proposed API would be of value to a larger audience.

The subjectivity of the market impact does not necessarily apply when changing or removing an API. In these cases, it should be possible to obtain objective data stating how many extensions use that API, and subsequently how many users would be impacted.

• Is there market evidence that developers are requesting this API? Are there numbers to support this?
• Does this API exist in other browsers already?Should it be implemented for parity?
• Does this API apply to a market niche, or could it be used by a large number of extensions?
• For changing/deprecating an API, how many extensions use the API? How many users does that represent?

IV. Abstraction

High-level APIs that are not tied to specific implementations or designs are better. An abstract API can exist independent of any particular user interface or platform. Within a browser this promotes maintainability, since the WebExtension API can remain constant even if the underlying implementation changes. In addition, an API that is defined at a high-level promotes cross-browser adoption.

Note that this criteria does not preclude new APIs that expose features available only on Firefox. However, it is best practice to define and structure any proposed API as generically as possible, such that the proposed API could conceivably be realized on other browsers, ideally on any platform. Nevertheless, no assumptions should be made about whether other browser vendors will implement the API, only if they could.

• Does the proposed API represent an abstract, high-level browser feature?
• Could other browsers potentially adopt this API, if desired?

V. Drawbacks

Every new API comes with some cost. What is that cost? Maybe it increases technical complexity, has a steep learning curve, or impacts the user experience in some way. While it is hard to enumerate all the possible ways that an API could have some downside, here are some common areas to think about.

• How difficult will it be to maintain and support the API?
• How complicated is the API for developers to learn and use?
• Is the underlying browser feature likely to be maintained into the future?
• Will the API impact browser performance?
• Does the API impact security or privacy (repeated, because it’s important)

VI. Alternatives

Preference will be given to APIs that open up functionality previously unavailable to developers. New APIs that simply make things easier will be considered, but should demonstrate significant savings in other areas such as extension development time or future support.

• Are there existing alternatives that give developers the same functionality?
• Why is the proposed API better than existing alternatives, if any?

The set of criteria listed above outlines the policy and guidelines regarding what should or should not be a WebExtensions API. Even if an API meets all of the criteria, it does not mean it will end up being implemented and supported by Firefox.

All new API are subject to the priorities of the Firefox product team. These priorities change over time, reacting to market demand and user feedback. If the proposed API is also aligned with the strategic and tactical priorities of Firefox, there is a very good chance it will be both approved and implemented.

However, there will almost certainly be proposed API that are good ideas, but are simply a low priority for one reason or another. Often times, an API requires a significant number of resources to implement, and the return on that investment isn’t high enough to justify the implementation. In these cases, the API may be approved but the implementation will be delayed indefinitely until resources are available (including community contributors) or priorities change.

Thanks to Rust for inspiring this document.