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`_ or the IRC #llvm channel on `irc.oftc.net`_.
  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 (unless stacked on another Differential), 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 We still have an active :ref:`Phabricator <phabricator-reviews>`
  93 instance for the duration of the migration. If you want to contribute to LLVM
  94 now, please use GitHub. For more information about the workflow of using GitHub
  95 Pull Requests see our :ref:`GitHub <github-reviews>` documentation.
  96
  97 To make sure the right people see your patch, please select suitable reviewers
  98 and add them to your patch when requesting a review. Suitable reviewers are the
  99 code owner (see CODE_OWNERS.txt) and other people doing work in the area your
 100 patch touches. Github will normally suggest some reviewers based on rules or
 101 people that have worked on the code before.
 102
 103 A reviewer may request changes or ask questions during the review. If you are
 104 uncertain on how to provide test cases, documentation, etc., feel free to ask
 105 for guidance during the review. Please address the feedback and re-post an
 106 updated version of your patch. This cycle continues until all requests and comments
 107 have been addressed and a reviewer accepts the patch with a `Looks good to me` or `LGTM`.
 108 Once that is done the change can be committed. If you do not have commit
 109 access, please let people know during the review and someone should commit it
 110 on your behalf.
 111
 112 If you have received no comments on your patch for a week, you can request a
 113 review by 'ping'ing the GitHub PR with "Ping." The common courtesy 'ping' rate
 114 is once a week. Please remember that you are asking for valuable time from other
 115 professional developers.
 116
 117 For more information on LLVM's code-review process, please see :doc:`CodeReview`.
 118
 119 .. _commit_from_git:
 120
 121 For developers to commit changes from Git
 122 -----------------------------------------
 123
 124 Once a patch is reviewed, you can select the "Squash and merge" button in the
 125 GitHub web interface. You might need to rebase your change before pushing
 126 it to the repo.
 127
 128 LLVM currently has a linear-history policy, which means that merge commits are
 129 not allowed. The `llvm-project` repo on github is configured to reject pushes
 130 that include merges, so the `git rebase` step above is required.
 131
 132 Please ask for help if you're having trouble with your particular git workflow.
 133
 134 .. _git_pre_push_hook:
 135
 136 Git pre-push hook
 137 ^^^^^^^^^^^^^^^^^
 138
 139 We include an optional pre-push hook that run some sanity checks on the revisions
 140 you are about to push and ask confirmation if you push multiple commits at once.
 141 You can set it up (on Unix systems) by running from the repository root:
 142
 143 .. code-block:: console
 144
 145   % ln -sf ../../llvm/utils/git/pre-push.py .git/hooks/pre-push
 146
 147 Helpful Information About LLVM
 148 ==============================
 149 :doc:`LLVM's documentation <index>` provides a wealth of information about LLVM's internals as
 150 well as various user guides. The pages listed below should provide a good overview
 151 of LLVM's high-level design, as well as its internals:
 152
 153 :doc:`GettingStarted`
 154    Discusses how to get up and running quickly with the LLVM infrastructure.
 155    Everything from unpacking and compilation of the distribution to execution
 156    of some tools.
 157
 158 :doc:`LangRef`
 159   Defines the LLVM intermediate representation.
 160
 161 :doc:`ProgrammersManual`
 162   Introduction to the general layout of the LLVM sourcebase, important classes
 163   and APIs, and some tips & tricks.
 164
 165 `LLVM for Grad Students`__
 166   This is an introduction to the LLVM infrastructure by Adrian Sampson. While it
 167   has been written for grad students, it provides  a good, compact overview of
 168   LLVM's architecture, LLVM's IR and how to write a new pass.
 169
 170   .. __: http://www.cs.cornell.edu/~asampson/blog/llvm.html
 171
 172 `Intro to LLVM`__
 173   Book chapter providing a compiler hacker's introduction to LLVM.
 174
 175   .. __: http://www.aosabook.org/en/llvm.html
 176
 177 .. _Forum: https://discourse.llvm.org
 178 .. _Discord server: https://discord.gg/xS7Z362
 179 .. _irc.oftc.net: irc://irc.oftc.net/llvm
 180 .. _good first issue: https://github.com/llvm/llvm-project/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22
 181 .. _bug tracker: https://github.com/llvm/llvm-project/issues
 182 .. _clang-format-diff.py: https://reviews.llvm.org/source/llvm-github/browse/main/clang/tools/clang-format/clang-format-diff.py
 183 .. _git-clang-format: https://reviews.llvm.org/source/llvm-github/browse/main/clang/tools/clang-format/git-clang-format
 184 .. _LLVM's GitHub: https://github.com/llvm/llvm-project
 185 .. _LLVM's Phabricator (deprecated): https://reviews.llvm.org/
 186 .. _LLVM's Open Projects page: https://llvm.org/OpenProjects.html#what