View source for Firefox/Go Faster/System Add-ons/Process

= Overview =

This document is a step-by-step guide for everything you need to deploy a system add-on.

This documentation leans heavier on a process of updates/fixes to existing versions of Firefox. For larger, feature-based add-ons, code may be required to live on pre-release channels longer before it is approved to move to production.

<small>An archive of the previous version of these docs can be found [[Firefox/Go_Faster/System_Add-On/Process_v1|here]].</small>

= Getting Started =

=== Is this something appropriate for a system add-on? ===

You can view our documentation here:
https://wiki.mozilla.org/Firefox/Go_Faster/When_To_Use_System_Add-ons

The major use cases for system add-ons is to roll out a vetted and QA'd feature or fix off of the standard release trains.

If you're thinking of [[Firefox/Making Network Requests From Firefox|Making Network Requests From Firefox]], there is specific guidance to follow.

=== Are there development resources for system add-ons? ===

We have a couple of repositories we ask users use to develop their system add-ons.

A large use case for system add-ons have been smaller one-off add-ons to ship fixes and updates (e.g. pref flips).

For these '''one-off add-ons''', you can visit https://github.com/mozilla/one-off-system-add-ons where you'll find example code, tests and more.

For '''larger, more complex add-ons''', you can visit https://github.com/mozilla/example-addon-repo with more resources.

=== Is this a one-off system add-on? ===

If yes, please create it in https://github.com/mozilla/one-off-system-add-ons/, as a bonus you can base it on the other add-ons that are in there.

=== Where can I find existing examples of system add-ons? ===

One-off system add-ons can be found here: https://github.com/mozilla/one-off-system-add-ons/

Go Faster System Add-ons will have [https://bugzilla.mozilla.org/buglist.cgi?list_id=13283590&status_whiteboard_type=substring&status_whiteboard=%5Bgo-faster-system-addon%5D&query_format=advanced WHITEBOARD=[go-faster-system-addon<nowiki>]</nowiki>]

Examples of a simple pref flip

* https://bugzilla.mozilla.org/show_bug.cgi?id=1306465
* https://bugzilla.mozilla.org/show_bug.cgi?id=1307108 

Examples of more complex feature add-ons

* https://bugzilla.mozilla.org/show_bug.cgi?id=1308656
* https://bugzilla.mozilla.org/show_bug.cgi?id=1280378
* https://bugzilla.mozilla.org/show_bug.cgi?id=1287966
* https://github.com/mozilla/example-addon-repo

=== More questions? ===

You can always cold-call gofaster@mozilla.org, or visit us in #gofaster to chat!

= Tracking Bug and Intent to Implement =

=== Tracking Bug ===

* Every system add-on should have a tracking bug (see Getting Started for examples).
* Product/Component is dependent on the add-on.
* Set the WHITEBOARD=[go-faster-system-addon] to allow the Go Faster team to track status.

=== Intent to Implement ===

* Intent to Implement emails are especially helpful for '''larger add-ons'''.
* This allows any potential interested parties to comment on the validity and testing requirements for the system add-on.
* More simple pref flip add-ons may not require an Intent to Implement email.
* A good example: https://mail.mozilla.org/pipermail/gofaster/2016-September/000434.html

The Intent to Implement email should have
{| class="wikitable"
|-
! Field !! Example
|-
| Tracking bug || see Getting Started for samples
|-
| References || Wiki page, or repository
|-
| Overview || What does the add-on do? What problem is it trying to fix?
|-
| Timeline || What is the rough timeline (and channel) for delivery?
|-
| mailto: || release-drivers@mozilla.org; gofaster@mozilla.org
|}

This early notification is also important for extremely timely system add-ons, and will prepare the teams for a fast turnaround.

'''Responsibility''': add-on developer/owner; interested parties to review

= QA and Code Review =

QA and code review of your XPI is the responsibility of the add-on developer/owner.

This can be done in a bug or GitHub issue. The end result is an agreement from the responsible QA party that the add-on is ready for release.

Once the add-on is approved, '''QA approval''' should be posted to the bug/issue, and/or sent through release-drivers@mozilla.org and gofaster@mozilla.org.

'''[https://bugzilla.mozilla.org/show_bug.cgi?id=1312528#c14 A signed XPI]''' should also be included in the bug.

'''Responsibility''': add-on developer/owner; code reviewer; QA

= Deployment Bug, Intent to Ship and RelMan Approval =

=== Deployment Bug ===
Once the add-on has been reviewed by QA, a [https://bugzilla.mozilla.org/enter_bug.cgi?product=Firefox&component=System%20Add-ons%3A%20Off-train%20Deployment deployment bug should be filed] under the "System Add-ons: Off-train Deployment" component. 

This bug should mark the tracking bug as a dependency. Additionally the bug should have the XPI file attached.

A sample bug can be found here: https://bugzilla.mozilla.org/show_bug.cgi?id=1546450

=== Intent to Ship === 
After filing the deployment bug, an Intent to Ship email should be sent.

Please expect a lead time of at least 3 business days between the email being sent, and the add-on released into production. Holidays and work weeks will effect scheduling.

The Intent to Ship email should have
{| class="wikitable"
|-
! Field !! Example
|-
| Deployment bug || filed under the System Add-ons: Off-train Deployment component
|-
| Tracking bug || see Getting Started for samples
|-
| System add-on || comment linking to signed XPI
|-
| Committed to mozilla-release || Was this committed to mozilla-release? If so, include commit ID
|-
| Verification || Link to comment with QA verification
|-
| User Impact || What are we fixing? What is the risk of this not going out?
|-
| Timeline || When does this need to go live?
|-
| Targeting Version || e.g. 49.0, 49.0.2, 50.*
|-
| Additional target rules || Are we targeting a specific OS, build ID, distribution, etc
|-
| mailto: || release-drivers@mozilla.org; gofaster@mozilla.org
|}

Example: https://mail.mozilla.org/pipermail/gofaster/2016-October/000507.html

=== Release Management Approval ===

The driver of the current release should Reply All to the Intent to Ship email with approval for release. In addition they should sign off in the deployment bug. Please request that they do so. 

Note that Release Management Approval does not necessarily all stakeholders are of aware of your add-on's effects. If you might impact other teams, be sure to contact them as well.

'''Responsibility''': add-on developer; release management

= Deployed to Test Channel =

After RelMan has approved the add-on for shipping, the Go Faster Team will update the test channel (`release-sysaddon`) in Balrog with the relevant rules and send out an email and post to the tracking bug.

These Deployed to Test Channel emails should include
{| class="wikitable"
|-
! Field !! Example
|-
| Versions affected || e.g. 49.0, 50.*
|-
| System add-on information || The ID's and versions of the system add-on(s)
|-
| Balrog details || Rules and releases modified in Balrog
|-
| mailto: || release-drivers@mozilla.org; gofaster@mozilla.org
|}

Examples
* https://mail.mozilla.org/pipermail/gofaster/2016-October/000511.html
* https://bugzilla.mozilla.org/show_bug.cgi?id=1312528#c16

'''Responsibility''': Go Faster Team

= Verification of Test Channel =

The purpose of this step is to receive verification that the add-on is being deployed correctly on the test channel (`release-sysaddon`).

This will be done by the QA team.

Notes on how best to verify system add-ons on the test channel can be found here: https://wiki.mozilla.org/Firefox/Go_Faster/Releasing_an_add-on_mechanics#Verifying_Balrog

Notes regarding coverage: https://public.etherpad-mozilla.org/p/sysaddon-balrog-verification

Once the test channel has been verified, a Reply All should be sent to the "Deployed to Test Channel" email.

'''Responsibility''': QA

= Push Release and Rules to Production =

Once the test channel is verified, the Go Faster team will update Balrog to the release channel, and update the bugs.

Example: https://bugzilla.mozilla.org/show_bug.cgi?id=1312528#c19

Once the rules have been updated in Balrog, the changes must be sign off by Relman/Releng.

Update Deployment Matrix: https://docs.google.com/spreadsheets/d/1yOgiOTU8q2I709VFhjCYCLATmoyQueV8RttPzciFIkQ/edit#gid=0

'''Responsibility''': Go Faster Team, Relman/Releng

= Measurement =

2016Q4 Goal is to track rollout of the add-on. See: https://wiki.mozilla.org/Firefox/Go_Faster/Measurement