Submitting a Gaia patch

By now you should have made a code change and verified that it hasn't broken Gaia. The next step is to submit your patch to the central repo, which is what this article explains.

Submitting patches to Gaia can be a little tricky until you get used to it, as it involves Bugzilla and Github, and usage of special flags in Bugzilla to make everything happen in the right sequence.

Easy patch submission with Autolander

Autolander is a tool that automatically handles a lot of the steps required for submitting patches to Gaia (and other projects it is being used with), saving time and cutting down on errors in the process. Autolander integrates the Bugzilla to Github workflow by attaching pull requests to bugs automatically, and other such things. To use Autolander:

First, submit a bug on bugzilla to indicate what you are doing, if one does not already exist for this code change. You should submit this under the Firefox OS product, and give it a nice descriptive title to say what your code does.
Now it is time to create a pull request for your patch. If you followed our guide from the start, you should have your changes made in a local fork of the Gaia repo and in a uniquely named branch. In case you haven't, you can use the commands below in order to have a ready local origin to modify.
```
git remote add gaia-mozilla https://github.com/mozilla-b2g/gaia/git fetch gaia-mozilla
git fetch gaia-mozilla
git checkout -b bug9999999_master gaia-mozilla/master
```
Next, git add . your changes, then git commit -m 'my commit message'.
'my commit message' needs to be substituted for a string containing the Bugzilla bug number and title of the bug, plus more information describing what the patch does, and who should review the commit. For example:
```
Bug 9999999 - Fix that annoying bug R=johndoe
```
Push the code to your Gaia fork on github.
```
git push origin bug9999999_master
```
Create a PR to offer the code up for inclusion in the main branch.
Once the pull request is opened, it will automatically be attached to the bug found in the PR title.
In the future, when the attachment has been given an r+ from a suggested reviewer, you can add the autoland keyword to the keywords field in order to land the code in Gaia master (meaning Autolander will land the code: merge the PR, put the commit into the bug, and mark the bug as resolved fixed.) HOWEVER, at the moment this part is still being worked on, so for now you'll have to add a checkin-needed keyword and wait for someone appropriate to land it for you.

Note: Autolander runs integration tests before landing in master. If the integration tests do not pass, Autolander will refuse to land the code. Some basic validations are performed such as making sure your pull request and commit message contain a bug number.

Note: Pull requests are landed in the order that they are requested to land. Pull requests are merged to an integration branch, and integration tests are run in parallel in this branch. If a PR fails the integration tests, it is rejected from the integration branch, and we rebuild the integration branch with the remaining commits. When a commit passes, we fast-forward master to that commit.

Note: If you need to push your patch to more branches (for instance to kanikani), you can proceed with the following commands after your push: git checkout -b bug9999999_kanikani gaia-mozilla/kanikani followed by git cherry-pick prevousCommitID and finally git push origin bug9999999_kanikani

Manual patch submission

If for some reason you don't want to rely on Autolander, follow these steps to submit your patch to Gaia manually.

First, submit a bug on bugzilla to indicate what you are doing, if one does not already exist for this code change. You should submit this under the Firefox OS product, and give it a nice descriptive title to say what your code does.
Now it is time to create a pull request for your patch. If you followed our guide from the start, you should have your changes made in a local fork of the Gaia repo and in a uniquely named branch. Next, git add . your changes, then git commit -m 'my commit message'.
'my commit message' needs to be substituted for a string containing the title of the bug, plus more information describing what the patch does, and who should review the commit. For example:
```
Bug 9999999 - Fix that annoying bug R=johndoe
```
Push the code to your Gaia fork on github, then create a PR to offer the code up for inclusion in the main branch.
Add the PR URL as an attachment to the Bug on bugzilla (follow the Add an attachment link, choose paste text as attachment if it is currently in the file input mode, enter the URL of the PR as the contents of the attachment, and enter a brief description.)
On the PR attachment to the Bugzilla bug, ask for a reviewer for your patch. You should do this by adding the review: ? flag to the attachment, then including the owner of the module your code applies to (see the Module owners page for more details.)
Wait for a reviewer to be assigned and review your patch. At this point they will probably include some comments asking for changes/fixes on the PR in Github, and link to them on Bugzilla.
Address the reviewer's comments, then push further changes to the same PR as before, reattaching the review: ? flag.
Once the reviewer's comments are addressed and they have given you the r+ flag (meaning it’s reviewed/approved), you should squash all your commits into one (also read the Tips_on_Gaia_Rebasing section below).
Add a checkin-needed keyword to the keywords field. At this point, you need to wait for someone to come and land your patch for you in the Gaia source (merge the PR, etc.)
Congratulations! Your code is now part of Firefox OS!

Note: We'd recommend sticking to one commit per review.

Note: further patch submission instructions can be found in contributing.md.

Tips on Gaia Rebasing

The Gaia master branch changes constantly (many, many times a day). After creating a patch that takes 2 hours, you might find that the master branch has changed underneath you.

From your working branch (e.g. my-code-fix), your first attempt to rebase will look something like this:

git checkout -b my-code-fix-r1
git pull --rebase upstream master

If there are no conflicts, you can carry on like this:

git checkout my-code-fix
git pull --rebase upstream master
git branch -D my-code-fix-r1

If you do find conflicts, work them out with the developers responsible for the conflicting changes and repeat the rebase procedure described above.

Status tracking versus engineering bugs

Mozilla has a special role called Sheriff. Sheriffs are in charge of merging code and maintaining branch status. Since we have limited sheriffs scouting for test failures in Firefox OS teams, it is hard for sheriffs to back out all imperfect patches.

In Firefox OS therefore, we prefer to open a new bug for landing new patches to fix an issue, if we encounter failure while examining whether a patch works or not. This causes some trouble for tracking status in QA and project management teams.

Therefore, we separate the bugs into status tracking bugs, and engineering bugs.

Status tracking bugs should be identified with a "meta" keyword. A status bug can be reopened if it doesn't meet the acceptance criteria or has failed during the steps to reproduce.
An engineering bug should be reopened only if it fails in automation testing or the patch totally doesn't work. If a patch fixes the engineering bug partilly, you should clone the bug and use the "see also" field to reference the original bug and describe the failure point.

Note: If it's also a user story bug, the project manager should fill the user story field with user story and acceptence criteria.

Recovering if you accidently land a patch on a status tracking bug

If you do this, don't panic. If you accidently land a patch, get review+, land it on the trunk, or have it reported as fixing nothing, here's what you'll need to do:

Press "Clone this bug" at the bottom right corner of the Bugzilla UI to create a new bug, cloning most of the original fields into it. Please check that whiteboard, keyword, and STR/user story are copied and pasted to the new bug.
Set the new bug as being blocked by the old bug. The new bug will be the new status tracking bug.
Use the needinfo flag to alert the appropriate project manager so they know the status tracking bug is changed. You can find e-mail addresses for the different project managers on Firefox OS on our Wiki.
Create a new engineer bug to describe the failure step or acceptance criteria. Also, use the new bug to block the status tracking bug.
Try to provide a fix for the new bug. Happy hacking!!!

Uplifting patches to older branches

You can see different version tags on bugs. If you want to uplift patches to an older branch of Firefox OS, check that they fulfill the patch landing rules. Find more details on our B2G Landing page.