docs/setup/contributing_code.rst

   1 How To Contribute Code To Firefox
   2 =================================
   3
   4 The whole process can be a bit long, and it might take time to get things right.
   5 If at any point you are 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.
   7
   8 We make changes to Firefox by writing patches, testing them and pushing them into "the tree", the
   9 term we use for all the code in Mozilla-Central. Let's get started.
  10
  11 Please see the :ref:`Firefox Contributors Quick Reference <Firefox Contributors' Quick Reference>` for simple check list.
  12
  13 Finding something to work on
  14 ----------------------------
  15
  16 | Bugs listed as 'Assigned' are not usually a good place to start,
  17   unless you're sure you have something worthy to contribute. Someone
  18   else is already working on it!
  19 | Even with no assignee, it is polite to check if someone has recently
  20   commented that they're looking at fixing the issue.
  21 | Once you have found something to work on, go ahead and comment! Let
  22   the bug submitter, reviewer, and component owner know that you'd like
  23   to work on the bug. You might receive some extra information, perhaps
  24   also made the assignee.
  25
  26 Find a bug we've identified as a good fit for new contributors.
  27 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  28
  29 With more than a million bugs filed in Bugzilla, it can be hard to know
  30 where to start, so we've created these bug categories to make getting
  31 involved a little easier:
  32
  33 -  `Codetribute <https://codetribute.mozilla.org/>`_ - our site for
  34    finding bugs that are mentored, some are good first bugs, some are
  35    slightly harder. Your mentor will help guide you with the bug fix and
  36    through the submission and landing process.
  37 -  `Good First Bugs <https://mzl.la/2yBg3zB>`_
  38    - are the best way to take your first steps into the Mozilla
  39    ecosystem. They're all about small changes, sometimes as little as a
  40    few lines, but they're a great way to learn about setting up your
  41    development environment, navigating Bugzilla, and making
  42    contributions to the Mozilla codebase.
  43 -  `Student Projects <https://bugzil.la/kw:student-project>`_ - are
  44    larger projects, such as might be suitable for a university student
  45    for credit. Of course, if you are not a student, feel free to fix one
  46    of these bugs. We maintain two lists: one for projects `based on the
  47    existing codebase <https://bugzil.la/kw:student-project>`_.
  48
  49 Fix that one bug
  50 ~~~~~~~~~~~~~~~~
  51
  52 If there's one particular bug you'd like to fix about Firefox, Thunderbird, or
  53 your other favorite Mozilla application, this can be a great place to
  54 start. There are a number of ways to do this:
  55
  56 -  `Search bugzilla <https://bugzilla.mozilla.org/query.cgi>`_ for
  57    relevant keywords. See pages on
  58    `Bugzilla and Searching Bugzilla <https://bmo.readthedocs.io/en/latest/using/finding.html>`_ for further
  59    help
  60 -  Learn the `bugzilla
  61    component <https://bugzilla.mozilla.org/describecomponents.cgi>`_,
  62    with which your pet bug is implemented, using the components list.
  63    Browse this component on bugzilla for related bugs
  64
  65 Fixing your bug
  66 ---------------
  67
  68 We leave this in your hands. Here are some further resources to help:
  69
  70 -  Check out
  71    :ref:`Our Developer Guide and its parent document <Working on Firefox>`
  72 -  Our :ref:`reviewer checklist <Reviewer Checklist>` is very
  73    useful, if you have a patch near completion, and seek a favorable
  74    review
  75 -  Utilize our build tool :ref:`mach`, its linting,
  76    static analysis, and other code checking features
  77
  78 Getting your code reviewed
  79 --------------------------
  80
  81 Once you fix the bug, you can advance to having your code reviewed.
  82
  83 Mozilla uses
  84 `Phabricator <https://moz-conduit.readthedocs.io/en/latest/phabricator-user.html>`_
  85 for code review.
  86
  87 Who is the right person to ask for a review?
  88
  89 -  If you have a mentored bug: ask your mentor. They will help, or can
  90    easily find out. It might be them!
  91 -  Run ``{hg, git} blame`` on the file and look for the people who have touched
  92    the functions you're working on. They too are good candidates.
  93    Running ``{hg, git} log`` and looking for regular reviewers might be a
  94    solution too.
  95 -  The bug itself may contain a clear indication of the best person to
  96    ask for a review
  97 -  Are there related bugs on similar topics? The reviewer in those bugs
  98    might be another good choice
  99 -  We have a :ref:`list of modules <Governance>`, which lists peers and
 100    owners for the module. Some of these will be good reviewers. In a
 101    worst case scenario, set the module owner as the reviewer, asking
 102    them in the comments to pick someone more suitable
 103
 104 Please select only one reviewer.
 105
 106 Following up and responding
 107 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 108
 109 Once you've asked for a review, a reviewer will often respond within a
 110 day or two, reviewing the patch, or saying when they will be able to
 111 review it, perhaps due to a backlog. If you don't hear back within this
 112 time, naturally reach out to them: add a comment to the bug saying
 113 'review ping?', check the "Need more information from" box, and add the
 114 reviewer's name. If they don't respond within a day or two, you can ask
 115 for help on Matrix in the
 116 `#introduction:mozilla.org <https://riot.im/app/#/room/#introduction:mozilla.org>`_
 117 or
 118 `#developers:mozilla.org <https://chat.mozilla.org/#/room/#developers:mozilla.org>`_
 119 channels.
 120
 121 Don't hesitate to contact your mentor as well if this isn't moving.
 122
 123 For most new contributors, and even for long-time Mozillians, the first
 124 review of your patch will be "Requested Changes" (or an "r-" in
 125 Bugzilla). This does not mean you've done bad work. There is more work
 126 to do before the code can be merged into the tree. Your patch may need
 127 some changes - perhaps minor, perhaps major - and your reviewer will
 128 give you some guidance on what needs to be done next.
 129
 130 This is an important process, so don't be discouraged! With our
 131 long-lived codebase, and hundreds of millions of users, the care and
 132 attention helping contributors bring good patches is the cornerstone of
 133 the Mozilla project. Make any changes your reviewer seeks; if you're
 134 unsure how, be sure to ask! Push your new patch up to Phabricator again and
 135 ask for a further review from the same reviewer. If they accept your
 136 changes, this means your patch can be landed into the tree!
 137
 138 Getting code into Firefox
 139 -------------------------
 140
 141 Once your patch has been accepted, it is ready to go. Before it can be
 142 merged into the tree, your patch will need to complete a successful run
 143 through our :ref:`try server <Pushing to Try>`,
 144 making sure there are no unexpected regressions. If you don't have try
 145 server access already, your mentor, or the person who reviewed your
 146 patch, will be able to help.
 147
 148 Ask the reviewer to land the patch for you.
 149 For more details, see :ref:`push_a_change`
 150
 151
 152 Do it all again!
 153 ----------------
 154
 155 Thank you. You've fixed your very first bug, and the Open Web is
 156 stronger for it. But don't stop now.
 157
 158 Go back to step 3, as there is plenty more to do. Your mentor might
 159 suggest a new bug for you to work on, or `find one that interests
 160 you <https://moztw.org/~petercpg/asknot/>`_. Now that you've got your
 161 first bug fixed you should request level 1 access to the repository to
 162 push to the try server and get automated feedback about your changes on
 163 multiple platforms. After fixing a nontrivial number of bugs you should
 164 request level 3 access so you can land your own code after it has been
 165 reviewed.
 166
 167 More information
 168 ----------------
 169
 170 We're in the process of improving information on this page for newcomers
 171 to the project. We'll be integrating some information from these pages
 172 soon, but until then you may find them interesting in their current
 173 form:
 174
 175 -  `A beginner's guide to SpiderMonkey, Mozilla's Javascript
 176    engine <https://wiki.mozilla.org/JavaScript:New_to_SpiderMonkey>`_