1 Firefox Contributors' Quick Reference
2 =====================================
4 Some parts of this process, including cloning and compiling, can take a long time even on modern hardware.
5 If at any point you get stuck, please don't hesitate to ask at `https://chat.mozilla.org <https://chat.mozilla.org>`__
6 in the `#introduction <https://chat.mozilla.org/#/room/#introduction:mozilla.org>`__ channel.
10 Please register and create your account for
12 `Bugzilla <https://bugzilla.mozilla.org/>`__ : web-based general-purpose bug tracking system.
13 To register with Phabricator, make sure you enable Two-Factor Authentication (My Profile >> Edit Profile & Preferences >> Two-Factor Authentication) in Bugzilla.
15 `Phabricator <https://phabricator.services.mozilla.com/>`__: web-based software development collaboration tools, mainly for code review.
16 Please obtain an API Token (Settings >> Conduit API Tokens)
21 You can use either mercurial or git. `Mercurial <https://www.mercurial-scm.org/downloads>`__ is the canonical version control system.
25 $ hg clone https://hg.mozilla.org/mozilla-central/
27 For git, see the `git cinnabar documentation <https://github.com/glandium/git-cinnabar/wiki/Mozilla:-A-git-workflow-for-Gecko-development>`__
29 The clone can take from 40 minutes to two hours (depending on your connection) and
30 the repository should be less than 5GB (~ 20GB after the build).
32 If you have any network connection issues and cannot clone with command, try :ref:`Mercurial bundles <Mercurial bundles>`.
34 :ref:`More information <Mercurial Overview>`
36 Install dependencies (non-Windows)
37 ----------------------------------
39 Firefox provides a mechanism to install all dependencies; in the source tree:
45 The default options are recommended.
46 If you're not planning to write C++ or Rust code, select :ref:`Artifact Mode <Understanding Artifact Builds>`
47 and follow the instructions at the end of the bootstrap for creating a mozconfig file.
49 More information :ref:`for Linux <Building Firefox On Linux>` and :ref:`for MacOS <Building Firefox On MacOS>`
54 #. You need 64-bit version of Windows 7 or later.
55 #. Download and install `Visual Studio Community Edition. <https://visualstudio.microsoft.com/downloads/>`__
56 #. Finally download the `MozillaBuild Package. <https://ftp.mozilla.org/pub/mozilla.org/mozilla/libraries/win32/MozillaBuildSetup-Latest.exe>`__ Installation directory should be:
62 #. Before moving on to the next steps, make sure to fulfill the :ref:`Windows prerequisites <Building Firefox On Windows>`
66 All the commands of this tutorial must be run in the shell provided with the MozillaBuild Package (start-shell.bat)
68 :ref:`More information <Building Firefox On Windows>`
73 Once all the dependencies have been installed, run:
79 which will check for dependencies and start the build.
80 This will take a while; a few minutes to a few hours depending on your hardware.
84 The default build is a compiled build with optimizations. Check out the
85 :ref:`mozconfig file documentation <Configuring Build Options>`
86 to see other build options. If you don't plan to change C++ or Rust code,
87 an :ref:`artifact build <Understanding Artifact Builds>` will be faster.
95 :ref:`More information about Linux <Building Firefox On Linux>` / :ref:`More information about MacOS <Building Firefox On MacOS>`
102 Make the changes you need in the codebase. You can look up UI text in `Searchfox <https://searchfox.org>`__ to find the right file.
106 .. code-block:: shell
116 The commit message should look like:
120 Bug xxxx - Short description of your change. r?reviewer
122 Optionally, a longer description of the change.
124 **Make sure you include the bug number and at least one reviewer (or reviewer group) in this format.**
126 To :ref:`find a reviewer or a review group <Getting reviews>`, the easiest way is to run
127 ``hg log <modified-file>`` (or ``git log <modified-file>``, if
128 you're using git) on the relevant files, and look who usually is
129 reviewing the actual changes (ie not reformat, renaming of variables, etc).
132 To visualize your patch in the repository, run:
134 .. code-block:: shell
142 :ref:`More information on how to work with stack of patches <Working with stack of patches Quick Reference>`
144 :ref:`More information <Mercurial Overview>`
146 To make sure the change follows the coding style
147 ------------------------------------------------
149 To detect coding style violations, use mach lint:
151 .. code-block:: shell
153 $ ./mach lint path/to/the/file/or/directory/you/changed
155 # To get the autofix, add --fix:
156 $ ./mach lint path/to/the/file/or/directory/you/changed --fix
158 :ref:`More information <Code quality>`
160 To test a change locally
161 ------------------------
163 To run the tests, use mach test with the path. However, it isn’t
164 always easy to parse the results.
166 .. code-block:: shell
168 $ ./mach test dom/serviceworkers
170 To run tests based on :ref:`GTest` (C/C++ based unit tests), run:
172 .. code-block:: shell
174 $ ./mach gtest 'QuotaManager.*'
176 To test a change remotely
177 -------------------------
179 Running all the tests for Firefox takes a very long time and requires multiple
180 operating systems with various configurations. To build Firefox and run its
181 tests on continuous integration servers (CI), multiple :ref:`options to select tasks <Selectors>`
184 To automatically select the tasks that are most likely to be affected by your changes, run:
186 .. code-block:: shell
190 To select tasks manually using a fuzzy search interface, run:
192 .. code-block:: shell
196 From `Treeherder <https://treeherder.mozilla.org/>`__ (our continuous integration system), it is also possible to attach new jobs. As every review has
197 a try CI run associated, it makes this work easier. See :ref:`attach-job-review` for
202 This requires `level 1 commit access <https://www.mozilla.org/about/governance/policies/commit/access-policy/>`__.
204 You can ask your reviewer to submit the patch for you if you don't have that
207 :ref:`More information <Pushing to Try>`
213 To submit a patch for review, we use a tool called `moz-phab <https://pypi.org/project/MozPhab/>`__.
216 .. code-block:: shell
218 $ ./mach install-moz-phab
220 Once you want to submit your patches (make sure you :ref:`use the right commit message <Commit message>`), run:
222 .. code-block:: shell
226 It will publish all the currently applied patches to Phabricator and inform the reviewer.
228 If you wrote several patches on top of each other:
230 .. code-block:: shell
232 $ moz-phab submit <first_revision>::<last_revision>
235 information <https://moz-conduit.readthedocs.io/en/latest/phabricator-user.html>`__
237 To update the working directory
238 -------------------------------
240 If you're finished with a patch and would like to return to the tip to make a new patch:
242 .. code-block:: shell
247 To update a submitted patch
248 ---------------------------
250 It is rare that a reviewer will accept the first version of patch. Moreover,
251 as the code review bot might suggest some improvements, changes to your patch
254 If your patch is not loaded in your working directory, you first need to re-apply it:
256 .. code-block:: shell
258 $ moz-phab patch D<revision_id>
260 Make your changes in the working folder and run:
262 .. code-block:: shell
264 # Or, if you need to pass arguments, e.g., changing the commit message:
270 After amending the patch, you will need to submit it using moz-phab again.
274 Don't use ``hg commit --amend -m`` or ``git commit --amend -m``.
276 Phabricator tracks revision by editing the commit message when a
277 revision is created to add a special ``Differential Revision:
280 When ``--amend -m`` is used, that line will be lost, leading to
281 the creation of a new revision when re-submitted, which isn't
284 If you wrote many changes, you can squash or edit commits with the
287 .. code-block:: shell
295 The submission step is the same as for the initial patch.
297 :ref:`More information on how to work with stack of patches <Working with stack of patches Quick Reference>`
299 Retrieve new changes from the repository
300 ----------------------------------------
302 To pull changes from the repository, run:
304 .. code-block:: shell
314 To push a change in the code base
315 ---------------------------------
317 Once the change has been accepted and you've fixed any remaining issues
318 the reviewer identified, the reviewer should land the patch.
320 If the patch has not landed on "autoland" (the integration branch) after a few days,
321 feel free to contact the reviewer and/or
322 @Aryx or @Sylvestre on the `#introduction <https://chat.mozilla.org/#/room/#introduction:mozilla.org>`__
325 The landing procedure will automatically close the review and the bug.
327 :ref:`More information <How to submit a patch>`
329 Contributing to GeckoView
330 -------------------------
332 Note that the GeckoView setup and contribution processes are different from those of Firefox;
333 GeckoView setup and contribution docs live in `geckoview.dev <https://geckoview.dev>`__.
335 More documentation about contribution
336 -------------------------------------
338 :ref:`Contributing to Mozilla projects`
340 https://mozilla-version-control-tools.readthedocs.io/en/latest/devguide/contributing.html
342 https://moz-conduit.readthedocs.io/en/latest/phabricator-user.html
344 https://mikeconley.github.io/documents/How_mconley_uses_Mercurial_for_Mozilla_code