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
   8 have questions, you can either use the `Developer's List (llvm-dev)`_
   9 or the #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 `beginner`_ 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 and 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 send a mail to
  49 the `LLVM Developer's mailing list`_, so that we know the project is being
  50 worked on.
  51
  52 How to Submit a Patch
  53 =====================
  54 Once you have a patch ready, it is time to submit it. The patch should:
  55
  56 * include a small unit test
  57 * conform to the :doc:`CodingStandards`. You can use the `clang-format-diff.py`_ or `git-clang-format`_ tools to automatically format your patch properly.
  58 * not contain any unrelated changes
  59 * be an isolated change. Independent changes should be submitted as separate patches as this makes reviewing easier.
  60
  61 .. _format patches:
  62
  63 Before sending a patch for review, please also try to ensure it is
  64 formatted properly. We use ``clang-format`` for this, which has git integration
  65 through the ``git-clang-format`` script. On some systems, it may already be
  66 installed (or be installable via your package manager). If so, you can simply
  67 run it -- the following command will format only the code changed in the most
  68 recent commit:
  69
  70 .. code-block:: console
  71
  72   % git clang-format HEAD~1
  73
  74 Note that this modifies the files, but doesn't commit them -- you'll likely want
  75 to run
  76
  77 .. code-block:: console
  78
  79   % git commit --amend -a
  80
  81 in order to update the last commit with all pending changes.
  82
  83 .. note::
  84   If you don't already have ``clang-format`` or ``git clang-format`` installed
  85   on your system, the ``clang-format`` binary will be built alongside clang, and
  86   the git integration can be run from
  87   ``clang/tools/clang-format/git-clang-format``.
  88
  89
  90 To get a patch accepted, it has to be reviewed by the LLVM community. This can
  91 be done using `LLVM's Phabricator`_ or the llvm-commits mailing list.
  92 Please  follow :ref:`Phabricator#phabricator-reviews <phabricator-reviews>`
  93 to request a review using Phabricator.
  94
  95 To make sure the right people see your patch, please select suitable reviewers
  96 and add them to your patch when requesting a review. Suitable reviewers are the
  97 code owner (see CODE_OWNERS.txt) and other people doing work in the area your
  98 patch touches. If you are using Phabricator, add them to the `Reviewers` field
  99 when creating a review and if you are using `llvm-commits`, add them to the CC of
 100 your email.
 101
 102 A reviewer may request changes or ask questions during the review. If you are
 103 uncertain on how to provide test cases, documentation, etc., feel free to ask
 104 for guidance during the review. Please address the feedback and re-post an
 105 updated version of your patch. This cycle continues until all requests and comments
 106 have been addressed and a reviewer accepts the patch with a `Looks good to me` or `LGTM`.
 107 Once that is done the change can be committed. If you do not have commit
 108 access, please let people know during the review and someone should commit it
 109 on your behalf.
 110
 111 If you have received no comments on your patch for a week, you can request a
 112 review by 'ping'ing a patch by responding to the email thread containing the
 113 patch, or the Phabricator review 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
 120 Helpful Information About LLVM
 121 ==============================
 122 :doc:`LLVM's documentation <index>` provides a wealth of information about LLVM's internals as
 123 well as various user guides. The pages listed below should provide a good overview
 124 of LLVM's high-level design, as well as its internals:
 125
 126 :doc:`GettingStarted`
 127    Discusses how to get up and running quickly with the LLVM infrastructure.
 128    Everything from unpacking and compilation of the distribution to execution
 129    of some tools.
 130
 131 :doc:`LangRef`
 132   Defines the LLVM intermediate representation.
 133
 134 :doc:`ProgrammersManual`
 135   Introduction to the general layout of the LLVM sourcebase, important classes
 136   and APIs, and some tips & tricks.
 137
 138 `LLVM for Grad Students`__
 139   This is an introduction to the LLVM infrastructure by Adrian Sampson. While it
 140   has been written for grad students, it provides  a good, compact overview of
 141   LLVM's architecture, LLVM's IR and how to write a new pass.
 142
 143   .. __: http://www.cs.cornell.edu/~asampson/blog/llvm.html
 144
 145 `Intro to LLVM`__
 146   Book chapter providing a compiler hacker's introduction to LLVM.
 147
 148   .. __: http://www.aosabook.org/en/llvm.html
 149
 150 .. _Developer's List (llvm-dev): http://lists.llvm.org/mailman/listinfo/llvm-dev
 151 .. _irc.oftc.net: irc://irc.oftc.net/llvm
 152 .. _beginner: https://github.com/llvm/llvm-project/issues?q=is%3Aopen+is%3Aissue+label%3Abeginner
 153 .. _bug tracker: https://github.com/llvm/llvm-project/issues
 154 .. _clang-format-diff.py: https://reviews.llvm.org/source/llvm-github/browse/main/clang/tools/clang-format/clang-format-diff.py
 155 .. _git-clang-format: https://reviews.llvm.org/source/llvm-github/browse/main/clang/tools/clang-format/git-clang-format
 156 .. _LLVM's Phabricator: https://reviews.llvm.org/
 157 .. _LLVM's Open Projects page: https://llvm.org/OpenProjects.html#what
 158 .. _LLVM Developer's mailing list: http://lists.llvm.org/mailman/listinfo/llvm-dev