Source Code Submission

When uploading extensions to addons.mozilla.org (AMO), you are given the option to attach source code. There are certain cases where this is required, but others where it is not recommended. This page will explain when and where source code should be uploaded, and how to provide reviewers with instructions on reading your source code. Providing clear instructions to the reviewer will help you get a speedier review for your add-on.

When to attach source code

When the add-on xpi file you upload to AMO contains code that is not completely readable by a human, it is probably a good idea to attach sources. Specifically, the following cases require you to upload sources:

• Add-ons using code minifiers or obfuscators, like uglifyJS or Google Closure Compiler.
• Add-ons that generate a single-file from various other files, for example using browserify.
• When using any other custom tool that take two or more files, apply pre-processing, and generate file(s) that are included in the add-on.
• When including a binary component, for example plugins, applets, dynamic libraries opened via js-ctypes, or for non-Firefox applications also binary XPCOM components.

There are also a few cases where it is actually NOT required and in fact not recommended. In these cases, please provide links to the files on the respective sites where you retrieved them. For repositories or version controlled files, please specify the link using the exact revision or tag that you have packaged. You should be retrieving the files from their official site for the download, not from a CDN or other location.

• When using only minified third party libraries, for example jQuery, Underscore or Angular
• When the libraries called via js-ctypes are known system or open source libraries.

The latest version of your source code needs to be attached to each version of your extension, not just the first. The source code must match the xpi file you have uploaded, as described later on this page.

How to upload source code

You can upload your sources in two ways. If you haven't already uploaded your new version, you can do it during the extension upload process:

If you have already uploaded your extension and would like to attach sources after the fact, head over to the version page by clicking on the respective version on the "Manage Status & Versions" page:

Requirements for the source package

When you attach sources, the add-on is marked for "admin-review". This means your sources are only accessible to a small group of admins. We do this to protect your sources.

A very important aspect of reviewing sources is reproducing the obfuscation. As we need to treat every extension developer the same, we must verify that the source code we reviewed matches the uploaded xpi. If we skip this step, a malware author could provide us with legitimate-looking sources and add a backdoor to the previously minified xpi file.

To reproduce the obfuscation, we run the instructions you've provided and then use a diff tool to compare the generated sources against the add-on xpi file. There must be no differences at all. The easiest way to do so is to include a README file in the uploaded sources. If it is just one or two files that are obfuscated, the instructions can be something like "run uglifyjs data/mycoolstuff.js". If the extension is any more complex, please provide a script that takes care of everything at once. Things you should mention in your README include:

• Prerequisites that need to be downloaded separately, for example yuicompressor.
• For less popular or custom-written build tools, provide links where they can be downloaded, as well as installation steps.
• If a specific version of supplemental software needs to be used, please let us know. But avoid doing so if the latest version would work just as well.
• All commands we should run to go from sources to a generated xpi file that matches the one you've uploaded, for example npm install or a grunt target.

Please assume the reviewer has a vanilla operating system set up. You don’t need to describe how to install common tools including npm, node, the add-on SDK, but please make sure the reviewer can figure out how to install everything needed to generate the xpi file. Aside from the README file, you also need to package everything required to build. If your add-on depends on a private repository or frameworks not commonly available, please include them as well.

If you skip any of the above steps, we will have to get in touch with you, adding time to the review process.

Example: Desired outcome

Common build tools used are make, grunt, gulp and ant. If you don't already have a build target that runs the above steps, please add a target that does so. For example, allow us to run grunt firefox-dist to create the generated xpi. Here is an example on what the sources could look like. The dist directory is initially empty, your build script (in this case grunt) then generates the directory contents, which you could zip up and upload to addons.mozilla.org.

sources
├── README.md                 
├── Gruntfile.js              
├── package.json               
├──────────────────────────────── dist
│                                 ├── bootstrap.js
│                                 ├── install.rdf
│                                 ├── package.json
├── data                          ├── data
│   ├── js                        │   ├── js
│   │   ├── dialog.js             │   │   ├── dialog.min.js
│   │   └── popup.js              │   │   └── popup.min.js
│   ├── scss                      │   ├── css
│   │   ├── popup.scss            │   │   ├── popup.css
│   │   ├── dialog.scss           │   │   └── dialog.scss
│   │   └── common.scss           │   │
│   ├── html                      │   ├── html
│   │   ├── dialog.html           │   │   ├── dialog.html
│   │   └── popup.html            │   │   └── popup.html
│   ├── vendor                    │   ├── vendor
│   │   └── jquery-2.1.4.min.js   │   │   └── jquery-2.1.4.min.js
│   └── images                    │   └── images
│       └── logo.png              │       └── logo.png
├── lib                           ├── lib
│   └── main.js                   │   └── main.js
└── locale                        └── locale
    └── en-US.properties              └── en-US.properties

Getting a faster review

In summary, there are few simple steps you can take to improve your review time. Foremost, if you can avoid obfuscating or minifying code, your review can be done by any reviewer, not only admins. But if you must attach source code, please do the following:

• Provide a README file with clear steps to take, based on a common vanilla operating system.
• Create a single script or build target that runs all needed steps, so all reviewers need to do is run it and compare the resulting directory with your uploaded xpi file.
• Use a well-known minification/obfuscation tool like uglifyJS or Google Closure Compiler.
• If more information is requested, please respond in a timely manner.