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