Landing a Patch
Tutorial on how to push approved and reviewed patches to the production server
To push a patch to comm-central, you'll need Level 3 Commit Access. You can learn more about Mozilla's commit access policies and start the process of signing up for an account here: Becoming a Mozilla Contributor
You'll need to add the address to your Mercurial configuration file at
default = https://hg.mozilla.org/comm-central
live-cc = ssh://hg.mozilla.org/comm-central
In this example we used the label
live-ccbut you can use whatever you like. Using the standard label
default-pushis not recommended – having to type the name of the repository helps prevent mistakes.
Is the tree open? Check TreeHerder – the name of the tree in the top-left corner shows you the status of the tree. Usually it's "open" (a green circle is displayed), which means you can push. Other statuses are "approval required" (yellow padlock) and "closed" (red X) which mean you can't push without permission, and in fact the server will prevent you from doing so.
Is it a good time to push? The best time to push is shortly after Mozilla updates the Firefox live server. Since Thunderbird builds on top of Firefox, pushing to live then will ensure that the build will get the latest changes.
Mozilla usually updates the Firefox Live Server around 0400, 1000, 1600, and 2200 UTC on weekdays and 1000 and 2200 UTC on weekends (give or take an hour). If one of these times is approaching, it's probably not a good time to push. You can check mozilla-central on TreeHerder to see when they last pushed.
Coordinate with others in the #maildev Matrix chat room as they may already be planning to push. A Firefox push is usually followed by an assigned person landing something to check the build is not broken.
Is there a build in progress already? If there is, please wait until you're reasonably sure the first build is not broken. In most cases this means that the Linux and OS X builds (B) are complete and tests (bct, X) are starting to turn green (free from major failures).
Is the tree green? If it isn't, do not push. Pushing something on top of an already broken build wastes resources (both computing and human).
Pushing to comm-central will create builds using the most recent mozilla-central code, which may or may not be a good idea at the time. Generally it's okay, but there may be unresolved problems between the two repositories. If you strike a problem, ask for help in the #maildev Matrix chat room.
Having gained level 3 access and configured Mercurial, you can push to comm-central. In general, it's just a matter of applying your patch(es) and running
hg push, but let's not do that right now as a series of important checks need to happen before.
These are a series of recommended steps to always go through before pushing to Live to ensure you're pushing only what you need.
Be sure your commit message is clear and has been approved during review. The standard syntax of a commit message is
Bug 000000 - Description of the patch and fix. r=reviewer.
Always check the reviewer in a commit message matches the person who actually reviewed the patch. A patch could be reviewed by someone other than the originally intended person, or it could have been sent to a group of reviewers.
hg qpop -ato clean your local queue.
hg into check if there are updates on the live server. (This isn't strictly necessary if you always do the next step.)
hg pull -uto download and apply the most recent changes.
- Reorder your queue and run
hg qpushto apply only the patches you want to push to Live.
hg qseriesto double check your have the right patches applied.
hg qfinish --appliedto include all the currently applied patches in your local tree.
hg outto see a list of patches that will be pushed to the Live server. Check your commit message(s) again.
hg push live-cc(or any shorthand you used in your
hgrcfile) to push your applied patches to comm-central.
hg pullto download and apply the most recent changes.
hg rebase -b my-bookmark-name -d XXXto rebase your patches. Replace the XXX with the latest public revision.
hg out -r my-bookmark-nameto see a list of patches that will be pushed to the Live server. Check only the patches you intend to send are listed. Check your commit message(s) again.
hg push live-cc -r my-bookmark-nameto push your applied patches to comm-central. Always specify a bookmark or revision to avoid sending more than one branch.
If your patch is faulty (i.e. it breaks the build or fails tests), it may be backed out without any warning. It's up to you to fix it.
The tree is monitored for failures by a team of people and although they are nice people they are not expected to tolerate your broken patch. A tree without failures is much easier to work with for everybody concerned.
Adding some magic words to the commit message of the tip-most revision will cause the build system to do different things. Getting it wrong or making a typo will not get the desired result.
DONTBUILDtells the build system not to build on this push. Only the decision and linting tasks will happen, unless another process comes along and starts a build, such as the Daily automatic build.
CLOSED TREEallows you to push to a closed tree. I hope you have permission!
a=approverYou must specify who approved the changes on some trees (not comm-central).
To land a patch you didn't write, e.g. from Bugzilla, you'll need to import it into Mercurial:
hg import -e https://bugzilla.mozilla.org/attachment.cgi?id=0000000
-eflag as above, or
hg commit --amendto edit the commit message as necessary.
To import a patch or patches from Phabricator, use
moz-phab patch --apply-to tip --no-bookmark --skip-dependencies D000000
--apply-toargument adds the patch to a specific parent revision, in this case the tip revision.
--no-bookmarkargument prevents a Mercurial bookmark from being created automatically. If you're just importing to land a patch, creating and then deleting a bookmark is just wasting your time.
--skip-dependenciesargument imports only the patch in question. Otherwise
moz-phabwill attempt to import all parent and child revisions in the Phabricator stack, including revisions that may already exist on your tree (and in this case fail miserably). You may want this to happen, in which case don't use this argument.
hg commit --amendor
hg histeditto adjust commit messages as necessary.
Our Phabricator installation has a system for automatically landing patches: Lando. To use it click "View stack in Lando" and follow the instructions. A few minutes may pass before an actual landing attempt happens. If it fails (usually because the patches do not apply cleanly) you'll be notified by email and will have to find a solution.
To land several patches together, create a "stack" of patches by using the "Edit related revisions…" and section in Phabricator. This can get messy so plan in advance. Check the current stack of any revision in the "Revision Contents" section of Phabricator.
If you worded your commit message correctly, a bot will post a message in your bug with a link to the changes you made, and close the bug. To prevent the bot from closing a bug, add the
leave-openkeyword to the bug before landing. The bot will automatically remove the
checkin-needed-tbflag if it is set.
At this point you should set the Target Milestone field in the bug to the current version, which is generally, but not always, the last option for that field.
You do not need to land patches on beta or ESR. We have authorised people to do that for you.
Request approval on Bugzilla in the same way you request review, using the
approval-comm-esrXXflags. Filling out the request form is not required. At an appropriate point approval will be granted (or denied!) and your patch will be landed for you.
Uplifting patches to earlier versions is for fixes to major bugs, and regressions that break the user interface. It should not be used as a shortcut to get new features to users earlier (some exceptions apply). The release channels ensure that changes are exposed to a test audience for a period of time before being shipped to all users.