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