224 lines · plain
1==================================2Contributing to LLVM3==================================4 5 6Thank you for your interest in contributing to LLVM! There are multiple ways to7contribute, and we appreciate all contributions. If you have questions,8you can either use the `Forum`_ or, for a more interactive chat, go to our9`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 Contribute18==================19 20Bug Reports21-----------22If you are working with LLVM and run into a bug, we definitely want to know23about it. Please follow the instructions in24:doc:`HowToSubmitABug` to create a bug report.25 26Bug Fixes27---------28If you are interested in contributing code to LLVM, bugs labeled with the29`good first issue`_ keyword in the `bug tracker`_ are a good way to get familiar with30the code base. If you are interested in fixing a bug, please comment on it to31let people know you are working on it.32 33Then try to reproduce and fix the bug with upstream LLVM. Start by building34LLVM from source as described in :doc:`GettingStarted` and35use the built binaries to reproduce the failure described in the bug. Use36a debug build (`-DCMAKE_BUILD_TYPE=Debug`) or a build with assertions37(`-DLLVM_ENABLE_ASSERTIONS=On`, enabled for Debug builds).38 39Reporting a Security Issue40--------------------------41 42There is a separate process to submit security-related bugs, see :ref:`report-security-issue`.43 44Bigger Pieces of Work45---------------------46If you are interested in taking on a bigger piece of work, a list of47interesting projects is maintained at the `LLVM's Open Projects page`_. If48you are interested in working on any of these projects, please post on the49`Forum`_, so that we know the project is being worked on.50 51.. _submit_patch:52 53How to Submit a Patch54=====================55Once you have a patch ready, it is time to submit it. The patch should:56 57* include a small unit test58* 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 changes60* 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 ensure it is66formatted properly. We use ``clang-format`` for this, which has git integration67through the ``git-clang-format`` script. On some systems, it may already be68installed (or be installable via your package manager). If so, you can simply69run it -- the following command will format only the code changed in the most70recent commit:71 72.. code-block:: console73 74 % git clang-format HEAD~175 76.. note::77 For some patches, formatting them may add changes that obscure the intent of78 the patch. For example, adding to an enum that was not previously formatted79 may result in the entire enum being reformatted. This happens because not all80 of the LLVM Project conforms to LLVM's clang-format style at this time.81 82 If you think that this might be the case for your changes, or are unsure, we83 recommend that you add the formatting changes as a **separate commit** within84 the Pull Request.85 86 Reviewers may request that this formatting commit be made into a separate Pull87 Request that will be merged before your actual changes.88 89 This means that if the formatting changes are the first commit, you will have90 an easier time doing this. If they are not, that is ok too, but you will have91 to do a bit more work to separate it out.92 93Note that ``git clang-format`` modifies the files, but does not commit them --94you will likely want to run one of the following to add the changes to a commit:95 96.. code-block:: console97 98 # To create a new commit.99 % git commit -a100 # To add to the most recent commit.101 % git commit --amend -a102 103.. note::104 If you don't already have ``clang-format`` or ``git clang-format`` installed105 on your system, the ``clang-format`` binary will be built alongside clang, and106 the git integration can be run from107 ``clang/tools/clang-format/git-clang-format``.108 109The LLVM project has migrated to GitHub Pull Requests as its review process.110For more information about the workflow of using GitHub Pull Requests see our111:ref:`GitHub <github-reviews>` documentation. We still have a read-only112`LLVM's Phabricator <https://reviews.llvm.org>`_ instance.113 114To make sure the right people see your patch, please select suitable reviewers115and add them to your patch when requesting a review.116 117Suitable reviewers are the maintainers of the project you are modifying, and118anyone else working in the area your patch touches. To find maintainers, look for119the ``Maintainers.md`` or ``Maintainers.rst`` file in the root of the project's120sub-directory. For example, LLVM's is ``llvm/Maintainers.md`` and Clang's is121``clang/Maintainers.rst``.122 123If you are a new contributor, you will not be able to select reviewers in such a124way, in which case you can still get the attention of potential reviewers by CC'ing125them in a comment -- just @name them.126 127If you have received no comments on your patch for a week, you can request a128review by 'ping'ing the GitHub PR with "Ping" in a comment. The common courtesy 'ping' rate129is once a week. Please remember that you are asking for valuable time from130other professional developers.131 132After your PR is approved, you can merge it. If you do not have the ability to133merge the PR, ask your reviewers to merge it on your behalf. You must do this134explicitly, as reviewers' default assumption is that you are able to merge your135own PR.136 137For more information on LLVM's code-review process, please see138:doc:`CodeReview`.139 140.. _commit_from_git:141 142For developers to commit changes from Git143-----------------------------------------144 145.. note::146 See also :ref:`GitHub <github-reviews>` for more details on merging your changes147 into LLVM project monorepo.148 149Once a pull request is approved, you can select the "Squash and merge" button in the150GitHub web interface.151 152When pushing directly from the command-line to the ``main`` branch, you will need153to rebase your change. LLVM has a linear-history policy, which means154that merge commits are not allowed, and the ``main`` branch is configured to reject155pushes that include merges.156 157GitHub will display a message that looks like this:158 159.. code-block:: console160 161 remote: Bypassed rule violations for refs/heads/main:162 remote:163 remote: - Required status check “buildkite/github-pull-requests” is expected.164 165This can seem scary, but this is just an artifact of the GitHub setup: it is166intended as a warning for people merging pull-requests with failing CI. We can't167disable it for people pushing on the command-line.168 169Please ask for help if you're having trouble with your particular git workflow.170 171.. _git_pre_push_hook:172 173Git pre-push hook174^^^^^^^^^^^^^^^^^175 176We include an optional pre-push hook that runs some sanity checks on the revisions177you are about to push and asks for confirmation if you push multiple commits at once.178You can set it up (on Unix systems) by running from the repository root:179 180.. code-block:: console181 182 % ln -sf ../../llvm/utils/git/pre-push.py .git/hooks/pre-push183 184Helpful Information About LLVM185==============================186:doc:`LLVM's documentation <index>` provides a wealth of information about LLVM's internals as187well as various user guides. The pages listed below should provide a good overview188of LLVM's high-level design, as well as its internals:189 190:doc:`GettingStarted`191 Discusses how to get up and running quickly with the LLVM infrastructure.192 Everything from unpacking and compilation of the distribution to execution193 of some tools.194 195:doc:`LangRef`196 Defines the LLVM intermediate representation.197 198:doc:`ProgrammersManual`199 Introduction to the general layout of the LLVM sourcebase, important classes200 and APIs, and some tips & tricks.201 202`LLVM for Grad Students`__203 This is an introduction to the LLVM infrastructure by Adrian Sampson. While it204 has been written for grad students, it provides a good, compact overview of205 LLVM's architecture, LLVM's IR and how to write a new pass.206 207 .. __: http://www.cs.cornell.edu/~asampson/blog/llvm.html208 209`Intro to LLVM`__210 Book chapter providing a compiler hacker's introduction to LLVM.211 212 .. __: http://www.aosabook.org/en/llvm.html213 214.. _Forum: https://discourse.llvm.org215.. _Discord server: https://discord.gg/xS7Z362216.. _irc.oftc.net: irc://irc.oftc.net/llvm217.. _good first issue: https://github.com/llvm/llvm-project/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22218.. _bug tracker: https://github.com/llvm/llvm-project/issues219.. _clang-format-diff.py: https://github.com/llvm/llvm-project/blob/main/clang/tools/clang-format/clang-format-diff.py220.. _git-clang-format: https://github.com/llvm/llvm-project/blob/main/clang/tools/clang-format/git-clang-format221.. _LLVM's GitHub: https://github.com/llvm/llvm-project222.. _LLVM's Phabricator (read-only): https://reviews.llvm.org/223.. _LLVM's Open Projects page: https://llvm.org/OpenProjects.html#what224