gecko-dev/docs/contributing/how_to_contribute_firefox.rst

How to contribute to Firefox
============================

This guide covers the basics of working on Firefox code. You'll learn how to set up your dev environment, build Firefox locally, and submit changes. The simplest commands are listed, with more detailed documentation linked from each section.

The whole process is a bit long, and it will take time to get things right.
If at any point you are stuck, please don't hesitate to ask at `https://chat.mozilla.org <https://chat.mozilla.org>`__
in the `#introduction <https://chat.mozilla.org/#/room/#introduction:mozilla.org>`__ channel.

Clone the sources
-----------------

You can use either mercurial or git. Mercurial is the canonical version control
system.

.. code-block:: shell

    $ hg clone https://hg.mozilla.org/mozilla-central/

For git, see the `git cinnabar documentation <https://github.com/glandium/git-cinnabar/wiki/Mozilla:-A-git-workflow-for-Gecko-development>`__

The clone should be around 30 minutes (depending on your connection) and
the repository should be less than 5GB (~ 20GB after the build).

If you have any network connection issues and cannot clone with command, try :ref:`Mercurial bundles <Mercurial bundles>`.

`More
information <https://developer.mozilla.org/docs/Mozilla/Developer_guide/Source_Code/Mercurial>`__

Install dependencies
--------------------

Firefox provides a mechanism to install all dependencies; in the source tree:

.. code-block:: shell

     $ ./mach bootstrap

The default options are recommended.
If you're not planning to write C++ or Rust code, select "`Artifact Mode <https://developer.mozilla.org/docs/Mozilla/Developer_guide/Build_Instructions/Artifact_builds>`__" 
and follow the instructions at the end of the bootstrap for creating a mozconfig file.

`More
information <https://developer.mozilla.org/docs/Mozilla/Developer_guide/Build_Instructions/Linux_Prerequisites>`__

Windows dependencies
--------------------

#. You need 64-bit version of Windows 7 or later.
#. Download and install `Visual Studio. <https://visualstudio.microsoft.com/downloads/>`__
#. Finally download the `MozillaBuild Package. <https://ftp.mozilla.org/pub/mozilla.org/mozilla/libraries/win32/MozillaBuildSetup-Latest.exe>`__ Installation directory should be:

.. code-block:: shell

    $ c:\mozilla-build\

`More
information <https://developer.mozilla.org/docs/Mozilla/Developer_guide/Build_Instructions/Windows_Prerequisites>`__


To build & run
--------------

Once all the dependencies have been installed, run:

.. code-block:: shell

     $ ./mach build

which will check for dependencies and start the build.
This will take a while; a few minutes to a few hours depending on your hardware.

To run it:

.. code-block:: shell

     $ ./mach run

`More
information <https://developer.mozilla.org/docs/Mozilla/Developer_guide/Build_Instructions/Simple_Firefox_build/Linux_and_MacOS_build_preparation>`__


To write a patch
----------------

Make the changes you need in the codebase. You can look up UI text in `Searchfox <https://searchfox.org>`__ to find the right file.

Then:

.. code-block:: shell

    # Mercurial
    $ hg commit

    # Git
    $ git commit

The commit message should look like:

.. code-block::

    Bug xxxx - Short description of your change. r?reviewer

    Optionally, a longer description of the change.

To :ref:`find a reviewer or a review group <Getting reviews>`, the easiest way is to do
``hg log <modified-file>`` (or ``git log <modified-file>``, if
you're using git) on the relevant files, and look who usually is
reviewing the actual changes (ie not reformat, renaming of variables, etc).

To visualize your patch in the repository, run:

.. code-block:: shell

    # Mercurial
    $ hg wip

    # Git
    $ git show


:ref:`More information <Mercurial Overview>`


To test a change locally
------------------------

To run the tests, use mach test with the path. However, it isn’t
always easy to parse the results.

.. code-block:: shell

    $ ./mach test dom/serviceworkers

`More information <https://developer.mozilla.org/docs/Mozilla/QA/Automated_testing>`__

To test a change remotely
-------------------------

Running all the tests for Firefox takes a very long time and requires multiple
operating systems with various configurations. To build Firefox and run its
tests on continuous integration servers (CI), two commands are available:

.. code-block:: shell

    $ ./mach try chooser

To select jobs running a fuzzy search:

.. code-block:: shell

    $ ./mach try fuzzy

From Treeherder, it is also possible to attach new jobs. As every review has
a try CI run associated, it makes this work easier. See :ref:`attach-job-review` for
more information.

.. note::

    This requires `level 1 commit access <https://www.mozilla.org/about/governance/policies/commit/access-policy/>`__.

    You can ask your reviewer to submit the patch for you if you don't have that
    level of access.

`More information <https://firefox-source-docs.mozilla.org/tools/try/index.html>`__


To submit a patch
-----------------

To submit a patch for review, we use a tool called `moz-phab <https://pypi.org/project/MozPhab/>`__.

.. code-block:: shell

     $ moz-phab

It will publish all the currently applied patches to Phabricator and inform the reviewer.

If you wrote several patches on top of each other:

.. code-block:: shell

    $ moz-phab submit <first_revision>::<last_revision>

`More
information <https://moz-conduit.readthedocs.io/en/latest/phabricator-user.html>`__

To update a submitted patch
---------------------------

It is rare that a reviewer will accept the first version of patch. Moreover,
as the code review bot might suggest some improvements, changes to your patch
may be required.

Run:

.. code-block:: shell

   # Mercurial
   $ hg commit --amend

   # Git
   $ git commit --amend

After amending the patch, you will need to submit it using moz-phab again.

If you wrote many changes, you can squash or edit commits with the
command:

.. code-block:: shell

   # Mercurial
   $ hg histedit

   # Git
   $ git rebase -i

The submission step is the same as for the initial patch.

Retrieve new changes from the repository
----------------------------------------

To pull changes from the repository, run:

.. code-block:: shell

   # Mercurial
   $ hg pull --rebase

   # Git
   $ git pull --rebase

To push a change in the code base
---------------------------------

Once the change has been accepted, ask the reviewer if they could land
the change. They don’t have an easy way to know if a contributor has
permission to land it or not.

If the reviewer does not land the patch after a few days, add
the *Check-in Needed* Tags to the review (*Edit Revision*).

The landing procedure will automatically close the review and the bug.

`More
information <https://developer.mozilla.org/docs/Mozilla/Developer_guide/How_to_Submit_a_Patch#Submitting_the_patch>`__

More documentation about contribution
-------------------------------------

https://developer.mozilla.org/docs/Mozilla/Developer_guide/Introduction

https://mozilla-version-control-tools.readthedocs.io/en/latest/devguide/contributing.html

https://moz-conduit.readthedocs.io/en/latest/phabricator-user.html