WebExtensions/Contribution Onramp

If this is your first contribution to the Firefox codebase, welcome! It can be scary to get started contributing to a large and complex codebase, but we’ve prepared some tips to help you fix a good-first-bug and land a patch in Firefox.

If we haven’t addressed your question in this document, please ask us by leaving a comment in the bug or by joining us on irc.mozilla.org in the #webextensions channel. For a general overview of how to contribute to Firefox, please go here.

General Tips

• To make sure your comment in Bugzilla is seen, please “needinfo” the bug’s mentor by checking the box that says “Needs more information from” and then selecting “mentor” from the drop down box.

Getting Started

• If you haven't already done so, create an account on https://bugzilla.mozilla.org.
• Pick a bug you want to work on from the good-first-bugs list.
• Comment on the bug that you would like to work on it and proceed to set up your developer environment.

Setting Up Developer Environment

• Now, you need to set up your development environment by building Firefox. There are two ways to do this:
  • [recommended] Build Firefox using Firefox Artifact builds. If the issue only requires changes to privileged JavaScript code, we recommend you use this method. Artifact builds saves time because it downloads a pre-built version of Firefox sources and applies your local changes on it, instead of rebuilding all of the C++ and Rust pieces from scratch.
  • Build Firefox from scratch. Note: doing this can take some time. After the initial build, you can build Firefox using the “mach build” command.

• Next, use Searchfox to quickly find the code associated with your bug.

WebExtensions APIs

You can learn more about how WebExtensions internals are organized and how to work on them by reading this internal API documentation and the WebExtensions Hacking wiki.

Testing

In order to land code in Firefox, you will need to create tests for your patches. For an overview of the different test systems Firefox uses, please see this overview of automated testing. In the WebExtension API code, most tests are either xpcshell tests or browser chrome tests. Xpcshell tests are preferred because of the lower overhead. Browser tests need to be written when a test interfaces with browser UI, such as tabs or context menus.

The easiest way to get started with tests is to look at existing tests:

• Xpcshell tests:
  • toolkit/components/extensions/test/xpcshell/ (Searchfox link)
  • browser/components/extensions/test/xpcshell/ (Searchfox link)

• Browser-chrome tests:
  • toolkit/components/extensions/test/browser/ (Searchfox link)
  • browser/components/extensions/test/browser/ (Searchfox link)

These tests can be run with the “mach test” command. To run a specific test, use “mach test [paths to test files or directories]”.

Add your test to an existing file when it is small and fits in that test. Otherwise, create a new test file, and register the test file in one of the .ini files in the same directory as your test, usually browser-common.ini or xpcshell-common.ini.

A test consists of multiple subtasks, which are defined in the test files via add_task(...). Most tests have the following minimal structure:

add_task(async function someShortAndSimpleDescriptionHere() {

 // Define a test extension.
 let extension = ExtensionTestUtils.loadExtension( .... );

 // Loads the actual extension.
 await extension.startup();

 // Tests here, often using extension.sendMessage and/or extension.awaitMessage

 // Unload the extension and remove the temporary files.
 await extension.unload();

});

ExtensionTestUtils.loadExtension allows you to quickly generate a test extension, and its input parameters are documented at: https://searchfox.org/mozilla-central/rev/ef8b3886cb173d5534b954b6fb7eb2d94a9473d0/toolkit/components/extensions/ExtensionTestCommon.jsm#185-212

Another common action in tests is to load a web page or extension page. In xpcshell-tests, use ExtensionTestUtils.loadContentPage.

In browser-chrome tests, the BrowserTestUtils namespace provides many useful test helpers, such as BrowserTestUtils.openNewForegroundTab to open a new tab. BrowserTestUtils is implemented and documented at https://searchfox.org/mozilla-central/source/testing/mochitest/BrowserTestUtils/BrowserTestUtils.jsm

Submitting a Patch

For an overview of how to submit a patch, please see this page on MDN.

• When you are ready to have your patch reviewed, submit your patch to Phabricator:
  • First, install the arc tool.
  • Then, use these instructions to submit the patch. Choose your mentor as the reviewer.
  • Note that you may go through a few iterations before your code is ready to go.
• When the patch is approved, add the keyword “checkin-needed” to the bug on Bugzilla. If you cannot add the keyword, please ask your mentor to add it for you.
• QA will verify your patch after it lands, unless your mentor has added a “qa-not-needed” keyword.
• Once your patch is accepted, you can expect to see your code in an upcoming version of Firefox!