llvm/docs/Contributing.rst

   1 ==================================
   2 Contributing to LLVM
   3 ==================================
   4
   5
   6 Thank you for your interest in contributing to LLVM! There are multiple ways to
   7 contribute, and we appreciate all contributions. In case you have questions,
   8 you can either use the `Forum`_ or, for a more interactive chat, go to our
   9 `Discord server`_.
  10
  11 If you want to contribute code, please familiarize yourself with the :doc:`DeveloperPolicy`.
  12
  13 .. contents::
  14   :local:
  15
  16
  17 Ways to Contribute
  18 ==================
  19
  20 Bug Reports
  21 -----------
  22 If you are working with LLVM and run into a bug, we definitely want to know
  23 about it. Please let us know and follow the instructions in
  24 :doc:`HowToSubmitABug`  to create a bug report.
  25
  26 Bug Fixes
  27 ---------
  28 If 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
  30 the code base. If you are interested in fixing a bug please comment on it to
  31 let people know you are working on it.
  32
  33 Then try to reproduce and fix the bug with upstream LLVM. Start by building
  34 LLVM from source as described in :doc:`GettingStarted` and
  35 use the built binaries to reproduce the failure described in the bug. Use
  36 a debug build (`-DCMAKE_BUILD_TYPE=Debug`) or a build with assertions
  37 (`-DLLVM_ENABLE_ASSERTIONS=On`, enabled for Debug builds).
  38
  39 Reporting a Security Issue
  40 --------------------------
  41
  42 There is a separate process to submit security-related bugs, see :ref:`report-security-issue`.
  43
  44 Bigger Pieces of Work
  45 ---------------------
  46 In case you are interested in taking on a bigger piece of work, a list of
  47 interesting projects is maintained at the `LLVM's Open Projects page`_. In case
  48 you 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
  53 How to Submit a Patch
  54 =====================
  55 Once 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
  65 Before sending a patch for review, please also try to ensure it is
  66 formatted properly. We use ``clang-format`` for this, which has git integration
  67 through the ``git-clang-format`` script. On some systems, it may already be
  68 installed (or be installable via your package manager). If so, you can simply
  69 run it -- the following command will format only the code changed in the most
  70 recent commit:
  71
  72 .. code-block:: console
  73
  74   % git clang-format HEAD~1
  75
  76 Note that this modifies the files, but doesn't commit them -- you'll likely want
  77 to run
  78
  79 .. code-block:: console
  80
  81   % git commit --amend -a
  82
  83 in 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
  91 The LLVM project has migrated to GitHub Pull Requests as its review process.
  92 For 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
  96 To make sure the right people see your patch, please select suitable reviewers
  97 and add them to your patch when requesting a review.
  98
  99 Suitable reviewers are the maintainers of the project you are modifying, and
 100 anyone else working in the area your patch touches. To find maintainers, look for
 101 the ``Maintainers.md`` or ``Maintainers.rst`` file in the root of the project's
 102 sub-directory. For example, LLVM's is ``llvm/Maintainers.md`` and Clang's is
 103 ``clang/Maintainers.rst``.
 104
 105 If you are a new contributor, you will not be able to select reviewers in such a
 106 way, in which case you can still get the attention of potential reviewers by CC'ing
 107 them in a comment -- just @name them.
 108
 109 If you have received no comments on your patch for a week, you can request a
 110 review by 'ping'ing the GitHub PR with "Ping" in a comment. The common courtesy 'ping' rate
 111 is once a week. Please remember that you are asking for valuable time from
 112 other professional developers.
 113
 114 After 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
 121 Now you can merge your PR. If you do not have the ability to merge the PR, ask your
 122 reviewers to merge it on your behalf. You must do this explicitly, as reviewers'
 123 default assumption is that you are able to merge your own PR.
 124
 125 For more information on LLVM's code-review process, please see
 126 :doc:`CodeReview`.
 127
 128 .. _commit_from_git:
 129
 130 For developers to commit changes from Git
 131 -----------------------------------------
 132
 133 Once a patch is reviewed, you can select the "Squash and merge" button in the
 134 GitHub web interface.
 135
 136 When pushing directly from the command-line to the ``main`` branch, you will need
 137 to rebase your change. LLVM has a linear-history policy, which means
 138 that merge commits are not allowed and the ``main`` branch is configured to reject
 139 pushes that include merges.
 140
 141 GitHub 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
 149 This can seem scary, but this is just an artifact of the GitHub setup: it is
 150 intended as a warning for people merging pull-requests with failing CI. We can't
 151 disable it for people pushing on the command-line.
 152
 153 Please ask for help if you're having trouble with your particular git workflow.
 154
 155 .. _git_pre_push_hook:
 156
 157 Git pre-push hook
 158 ^^^^^^^^^^^^^^^^^
 159
 160 We include an optional pre-push hook that run some sanity checks on the revisions
 161 you are about to push and ask confirmation if you push multiple commits at once.
 162 You 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
 168 Helpful Information About LLVM
 169 ==============================
 170 :doc:`LLVM's documentation <index>` provides a wealth of information about LLVM's internals as
 171 well as various user guides. The pages listed below should provide a good overview
 172 of 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