contributing-to-firefox.rst (5876B)
1 .. -*- Mode: rst; fill-column: 80; -*- 2 3 ========================= 4 Firefox Contributor Guide 5 ========================= 6 7 Table of contents 8 ================= 9 10 .. contents:: :local: 11 12 Submitting a patch to Firefox using Git. 13 ======================================== 14 .. _contribute_with_git: 15 16 This guide will take you through submitting and updating a patch to 17 ``firefox`` as a git user. You need to already be `set up to use 18 git to contribute to Firefox </setup/index.html>`_. 19 20 Performing a bug fix 21 -------------------- 22 23 All of the open bugs for issues in Firefox can be found in 24 `Bugzilla <https://bugzilla.mozilla.org>`_. If you know the component 25 that you wish to contribute to you can use Bugzilla to search for issues 26 in that project. If you are unsure which component you are interested 27 in, you can search the `Good First 28 Bugs <https://bugzilla.mozilla.org/buglist.cgi?quicksearch=good-first-bug>`_ 29 list to find something you want to work on. 30 31 - Once you have your bug, assign it to yourself in Bugzilla. 32 - Update your local copy of the firefox codebase to match the current 33 version on the servers to ensure you are working with the most up to 34 date code. 35 36 .. code:: bash 37 38 git remote update 39 40 - Create a new feature branch tracking either main or autoland. 41 42 .. code:: bash 43 44 git checkout -b bugxxxxxxx [main|autoland]/default 45 46 - Work on your bug, checking into git according to your preferred 47 workflow. *Try to ensure that each individual commit compiles and 48 passes all of the tests for your component. This will make it easier 49 to land if you use ``moz-phab`` to submit (details later in this 50 post).* 51 52 It may be helpful to have Mozilla commit access, at least level 1. There 53 are three levels of commit access that give increasing levels of access 54 to the repositories. 55 56 Level 1: Try/User access. You will need this level of access commit to 57 the try server. 58 59 Level 2: General access. This will give you full commit 60 access to any mercurial or SVN repository not requiring level 3 access. 61 62 Level 3: Core access. You will need this level to commit directly to any 63 of the core repositories (Firefox/Thunderbird/Fennec). 64 65 If you wish to apply for commit access, please follow the guide found in 66 the `Mozilla Commit Access 67 Policy <https://www.mozilla.org/en-US/about/governance/policies/commit/access-policy/>`_. 68 69 Submitting a patch that touches C/C++ 70 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 71 72 If your patch makes changes to any C or C++ code and your editor does 73 not have ``clang-format`` support, you should run the clang-format 74 linter before submitting your patch to ensure that your code is properly 75 formatted. 76 77 .. code:: bash 78 79 mach clang-format -p path/to/file.cpp 80 81 Note that ``./mach bootstrap`` will offer to set up a commit hook that 82 will automatically do this for you. 83 84 Submitting to ``try`` with Level 1 commit access. 85 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 86 87 If you only have Level 1 access, you will still need to submit your 88 patch through phabricator, but you can test it on the try server first. 89 90 - Use ``./mach try fuzzy`` to select jobs to run and push to try. 91 92 Submitting a patch via Phabricator. 93 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 94 95 To commit anything to the repository, you will need to set up moz-phab 96 and Phabricator. If you are using ``git-cinnabar`` then you will need to 97 use git enabled versions of these tools. 98 99 Set up Phabricator 100 ^^^^^^^^^^^^^^^^^^ 101 102 - In a browser, visit Mozilla’s Phabricator instance at 103 https://phabricator.services.mozilla.com/. 104 105 - Click “Log In” at the top of the page 106 107 .. figure:: ../assets/LogInPhab.png 108 :alt: Log in to Phabricator 109 110 alt text 111 112 - Click the “Log In or Register” button on the next page. This will 113 take you to Bugzilla to log in or register a new account. 114 115 .. figure:: ../assets/LogInOrRegister.png 116 :alt: Log in or register a Phabiricator account 117 118 alt text 119 120 - Sign in with your Bugzilla credentials, or create a new account. 121 122 .. figure:: ../assets/LogInBugzilla.png 123 :alt: Log in with Bugzilla 124 125 alt text 126 127 - You will be redirected back to Phabricator, where you will have to 128 create a new Phabricator account. 129 130 .. raw:: html 131 132 <Screenshot Needed> 133 134 - Fill in/amend any fields on the form and click “Register Account”. 135 136 .. raw:: html 137 138 <Screenshot Needed> 139 140 - You now have a Phabricator account and can submit and review patches. 141 142 Installing ``moz-phab`` 143 ^^^^^^^^^^^^^^^^^^^^^^^ 144 145 .. code:: bash 146 147 pip install MozPhab [--user] 148 149 Submitting a patch using ``moz-phab``. 150 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 151 152 - Ensure you are on the branch where you have commits that you want to 153 submit. 154 155 .. code:: bash 156 157 git checkout your-branch 158 159 - Check the revision numbers for the commits you want to submit 160 161 .. code:: bash 162 163 git log 164 165 - Run ``moz-phab``. Specifying a start commit will submit all commits 166 from that commit. Specifying an end commit will submit all commits up 167 to that commit. If no positional arguments are provided, the range is 168 determined to be starting with the first non-public, non-obsolete 169 changeset (for Mercurial) and ending with the currently checked-out 170 changeset. 171 172 .. code:: bash 173 174 moz-phab submit [start_rev] [end_rev] 175 176 - You will receive a Phabricator link for each commit in the set. 177 178 Updating a patch 179 ~~~~~~~~~~~~~~~~ 180 181 - Often you will need to make amendments to a patch after it has been 182 submitted to address review comments. To do this, add your commits to 183 the base branch of your fix as normal. 184 185 For ``moz-phab`` run in the same way as the initial submission with the 186 same arguments, that is, specifying the full original range of commits. 187 Note that, while inserting and amending commits should work fine, 188 reordering commits is not yet supported, and deleting commits will leave 189 the associated revisions open, which should be abandoned manually