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 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 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 an out of date `list of
 100    modules <https://wiki.mozilla.org/Modules>`_, which lists peers and
 101    owners for the module. Some of these will be good reviewers. In a
 102    worst case scenario, set the module owner as the reviewer, asking
 103    them in the comments to pick someone more suitable
 104
 105 Please select only one reviewer.
 106
 107 Following up and responding
 108 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 109
 110 Once you've asked for a review, a reviewer will often respond within a
 111 day or two, reviewing the patch, or saying when they will be able to
 112 review it, perhaps due to a backlog. If you don't hear back within this
 113 time, naturally reach out to them: add a comment to the bug saying
 114 'review ping?', check the "Need more information from" box, and add the
 115 reviewer's name. If they don't respond within a day or two, you can ask
 116 for help on Matrix in the
 117 `#introduction:mozilla.org <https://riot.im/app/#/room/#introduction:mozilla.org>`_
 118 or
 119 `#developers:mozilla.org <https://chat.mozilla.org/#/room/#developers:mozilla.org>`_
 120 channels, or contact `Mike
 121 Hoye <mailto:mhoye@mozilla.com?subject=Code%20Review%20Request%20&body=URL%3A%20%20%5Bplease%20paste%20a%20link%20to%20your%20patch%20here.%5D>`_
 122 directly.
 123
 124 Don't hesitate to contact your mentor as well if this isn't moving.
 125
 126 For most new contributors, and even for long-time Mozillians, the first
 127 review of your patch will be "Requested Changes" (or an "r-" in
 128 Bugzilla). This does not mean you've done bad work. There is more work
 129 to do before the code can be merged into the tree. Your patch may need
 130 some changes - perhaps minor, perhaps major - and your reviewer will
 131 give you some guidance on what needs to be done next.
 132
 133 This is an important process, so don't be discouraged! With our
 134 long-lived codebase, and hundreds of millions of users, the care and
 135 attention helping contributors bring good patches is the cornerstone of
 136 the Mozilla project. Make any changes your reviewer seeks; if you're
 137 unsure how, be sure to ask! Push your new patch up to Phabricator again and
 138 ask for a further review from the same reviewer. If they accept your
 139 changes, this means your patch can be landed into the tree!
 140
 141 Getting code into Firefox
 142 -------------------------
 143
 144 Once your patch has been accepted, it is ready to go. Before it can be
 145 merged into the tree, your patch will need to complete a successful run
 146 through our `try
 147 server <https://wiki.mozilla.org/ReleaseEngineering/TryServer>`_,
 148 making sure there are no unexpected regressions. If you don't have try
 149 server access already, your mentor, or the person who reviewed your
 150 patch, will be able to help.
 151
 152 Ask the reviewer to land the patch for you.
 153 For more details, see :ref:`push_a_change`
 154
 155
 156 Do it all again!
 157 ----------------
 158
 159 Thank you. You've fixed your very first bug, and the Open Web is
 160 stronger for it. But don't stop now.
 161
 162 Go back to step 3, as there is plenty more to do. Your mentor might
 163 suggest a new bug for you to work on, or `find one that interests
 164 you <http://www.whatcanidoformozilla.org/>`_. Now that you've got your
 165 first bug fixed you should request level 1 access to the repository to
 166 push to the try server and get automated feedback about your changes on
 167 multiple platforms. After fixing a nontrivial number of bugs you should
 168 request level 3 access so you can land your own code after it has been
 169 reviewed.
 170
 171 More information
 172 ----------------
 173
 174 We're in the process of improving information on this page for newcomers
 175 to the project. We'll be integrating some information from these pages
 176 soon, but until then you may find them interesting in their current
 177 form:
 178
 179 -  `A guide to learning the Firefox
 180    codebase <http://www.joshmatthews.net/blog/2010/03/getting-involve-with-mozilla/>`_
 181 -  `A beginner's guide to SpiderMonkey, Mozilla's Javascript
 182    engine <https://wiki.mozilla.org/JavaScript:New_to_SpiderMonkey>`_
 183 -  `Mozilla platform development
 184    cheatsheet <https://web.archive.org/web/20160813112326/http://www.codefirefox.com:80/cheatsheet>`_
 185    (archive.org)