1================================== 2Contributing to LLVM 3================================== 4 5 6Thank you for your interest in contributing to LLVM! There are multiple ways to 7contribute, and we appreciate all contributions. In case you have questions, 8you can either use the `Forum`_ or, for a more interactive chat, go to our 9`Discord server`_. 10 11If you want to contribute code, please familiarize yourself with the :doc:`DeveloperPolicy`. 12 13.. contents:: 14 :local: 15 16 17Ways to Contribute 18================== 19 20Bug Reports 21----------- 22If you are working with LLVM and run into a bug, we definitely want to know 23about it. Please let us know and follow the instructions in 24:doc:`HowToSubmitABug` to create a bug report. 25 26Bug Fixes 27--------- 28If you are interested in contributing code to LLVM, bugs labeled with the 29`good first issue`_ keyword in the `bug tracker`_ are a good way to get familiar with 30the code base. If you are interested in fixing a bug please comment on it to 31let people know you are working on it. 32 33Then try to reproduce and fix the bug with upstream LLVM. Start by building 34LLVM from source as described in :doc:`GettingStarted` and 35use the built binaries to reproduce the failure described in the bug. Use 36a debug build (`-DCMAKE_BUILD_TYPE=Debug`) or a build with assertions 37(`-DLLVM_ENABLE_ASSERTIONS=On`, enabled for Debug builds). 38 39Reporting a Security Issue 40-------------------------- 41 42There is a separate process to submit security-related bugs, see :ref:`report-security-issue`. 43 44Bigger Pieces of Work 45--------------------- 46In case you are interested in taking on a bigger piece of work, a list of 47interesting projects is maintained at the `LLVM's Open Projects page`_. In case 48you are interested in working on any of these projects, please post on the 49`Forum`_, so that we know the project is being worked on. 50 51.. _submit_patch: 52 53How to Submit a Patch 54===================== 55Once you have a patch ready, it is time to submit it. The patch should: 56 57* include a small unit test 58* conform to the :doc:`CodingStandards`. You can use the `clang-format-diff.py`_ or `git-clang-format`_ tools to automatically format your patch properly. 59* not contain any unrelated changes 60* be an isolated change. Independent changes should be submitted as separate patches as this makes reviewing easier. 61* have a single commit, up-to-date with the upstream ``origin/main`` branch, and don't have merges. 62 63.. _format patches: 64 65Before sending a patch for review, please also try to ensure it is 66formatted properly. We use ``clang-format`` for this, which has git integration 67through the ``git-clang-format`` script. On some systems, it may already be 68installed (or be installable via your package manager). If so, you can simply 69run it -- the following command will format only the code changed in the most 70recent commit: 71 72.. code-block:: console 73 74 % git clang-format HEAD~1 75 76Note that this modifies the files, but doesn't commit them -- you'll likely want 77to run 78 79.. code-block:: console 80 81 % git commit --amend -a 82 83in order to update the last commit with all pending changes. 84 85.. note:: 86 If you don't already have ``clang-format`` or ``git clang-format`` installed 87 on your system, the ``clang-format`` binary will be built alongside clang, and 88 the git integration can be run from 89 ``clang/tools/clang-format/git-clang-format``. 90 91The LLVM project has migrated to GitHub Pull Requests as its review process. 92For more information about the workflow of using GitHub Pull Requests see our 93:ref:`GitHub <github-reviews>` documentation. We still have an read-only 94`LLVM's Phabricator <https://reviews.llvm.org>`_ instance. 95 96To make sure the right people see your patch, please select suitable reviewers 97and add them to your patch when requesting a review. 98 99Suitable reviewers are the maintainers of the project you are modifying, and 100anyone else working in the area your patch touches. To find maintainers, look for 101the ``Maintainers.md`` or ``Maintainers.rst`` file in the root of the project's 102sub-directory. For example, LLVM's is ``llvm/Maintainers.md`` and Clang's is 103``clang/Maintainers.rst``. 104 105If you are a new contributor, you will not be able to select reviewers in such a 106way, in which case you can still get the attention of potential reviewers by CC'ing 107them in a comment -- just @name them. 108 109If you have received no comments on your patch for a week, you can request a 110review by 'ping'ing the GitHub PR with "Ping" in a comment. The common courtesy 'ping' rate 111is once a week. Please remember that you are asking for valuable time from 112other professional developers. 113 114After your PR is approved, ensure that: 115 116 * The PR title and description describe the final changes. These will be used 117 as the title and message of the final squashed commit. The titles and 118 messages of commits in the PR will **not** be used. 119 * You have set a valid email address in your GitHub account, see :ref:`github-email-address`. 120 121Now you can merge your PR. If you do not have the ability to merge the PR, ask your 122reviewers to merge it on your behalf. You must do this explicitly, as reviewers' 123default assumption is that you are able to merge your own PR. 124 125For more information on LLVM's code-review process, please see 126:doc:`CodeReview`. 127 128.. _commit_from_git: 129 130For developers to commit changes from Git 131----------------------------------------- 132 133Once a patch is reviewed, you can select the "Squash and merge" button in the 134GitHub web interface. 135 136When pushing directly from the command-line to the ``main`` branch, you will need 137to rebase your change. LLVM has a linear-history policy, which means 138that merge commits are not allowed and the ``main`` branch is configured to reject 139pushes that include merges. 140 141GitHub will display a message that looks like this: 142 143.. code-block:: console 144 145 remote: Bypassed rule violations for refs/heads/main: 146 remote: 147 remote: - Required status check “buildkite/github-pull-requests” is expected. 148 149This can seem scary, but this is just an artifact of the GitHub setup: it is 150intended as a warning for people merging pull-requests with failing CI. We can't 151disable it for people pushing on the command-line. 152 153Please ask for help if you're having trouble with your particular git workflow. 154 155.. _git_pre_push_hook: 156 157Git pre-push hook 158^^^^^^^^^^^^^^^^^ 159 160We include an optional pre-push hook that run some sanity checks on the revisions 161you are about to push and ask confirmation if you push multiple commits at once. 162You can set it up (on Unix systems) by running from the repository root: 163 164.. code-block:: console 165 166 % ln -sf ../../llvm/utils/git/pre-push.py .git/hooks/pre-push 167 168Helpful Information About LLVM 169============================== 170:doc:`LLVM's documentation <index>` provides a wealth of information about LLVM's internals as 171well as various user guides. The pages listed below should provide a good overview 172of LLVM's high-level design, as well as its internals: 173 174:doc:`GettingStarted` 175 Discusses how to get up and running quickly with the LLVM infrastructure. 176 Everything from unpacking and compilation of the distribution to execution 177 of some tools. 178 179:doc:`LangRef` 180 Defines the LLVM intermediate representation. 181 182:doc:`ProgrammersManual` 183 Introduction to the general layout of the LLVM sourcebase, important classes 184 and APIs, and some tips & tricks. 185 186`LLVM for Grad Students`__ 187 This is an introduction to the LLVM infrastructure by Adrian Sampson. While it 188 has been written for grad students, it provides a good, compact overview of 189 LLVM's architecture, LLVM's IR and how to write a new pass. 190 191 .. __: http://www.cs.cornell.edu/~asampson/blog/llvm.html 192 193`Intro to LLVM`__ 194 Book chapter providing a compiler hacker's introduction to LLVM. 195 196 .. __: http://www.aosabook.org/en/llvm.html 197 198.. _Forum: https://discourse.llvm.org 199.. _Discord server: https://discord.gg/xS7Z362 200.. _irc.oftc.net: irc://irc.oftc.net/llvm 201.. _good first issue: https://github.com/llvm/llvm-project/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22 202.. _bug tracker: https://github.com/llvm/llvm-project/issues 203.. _clang-format-diff.py: https://github.com/llvm/llvm-project/blob/main/clang/tools/clang-format/clang-format-diff.py 204.. _git-clang-format: https://github.com/llvm/llvm-project/blob/main/clang/tools/clang-format/git-clang-format 205.. _LLVM's GitHub: https://github.com/llvm/llvm-project 206.. _LLVM's Phabricator (read-only): https://reviews.llvm.org/ 207.. _LLVM's Open Projects page: https://llvm.org/OpenProjects.html#what 208