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 create an account
  31 for the bug tracker and assign it to yourself, to let people know you are working on
  32 it.
  33
  34 Then try to reproduce and fix the bug with upstream LLVM. Start by building
  35 LLVM from source as described in :doc:`GettingStarted` and
  36 and use the built binaries to reproduce the failure described in the bug. Use
  37 a debug build (`-DCMAKE_BUILD_TYPE=Debug`) or a build with assertions
  38 (`-DLLVM_ENABLE_ASSERTIONS=On`, enabled for Debug builds).
  39
  40 Bigger Pieces of Work
  41 ---------------------
  42 In case you are interested in taking on a bigger piece of work, a list of
  43 interesting projects is maintained at the `LLVM's Open Projects page`_. In case
  44 you are interested in working on any of these projects, please send a mail to
  45 the `LLVM Developer's mailing list`_, so that we know the project is being
  46 worked on.
  47
  48
  49 How to Submit a Patch
  50 =====================
  51 Once you have a patch ready, it is time to submit it. The patch should:
  52
  53 * include a small unit test
  54 * conform to the :doc:`CodingStandards`. You can use the `clang-format-diff.py`_ or `git-clang-format`_ tools to automatically format your patch properly.
  55 * not contain any unrelated changes
  56 * be an isolated change. Independent changes should be submitted as separate patches as this makes reviewing easier.
  57
  58 To get a patch accepted, it has to be reviewed by the LLVM community. This can
  59 be done using `LLVM's Phabricator`_ or the llvm-commits mailing list.
  60 Please  follow :ref:`Phabricator#requesting-a-review-via-the-web-interface <phabricator-request-review-web>`
  61 to request a review using Phabricator.
  62
  63 To make sure the right people see your patch, please select suitable reviewers
  64 and add them to your patch when requesting a review. Suitable reviewers are the
  65 code owner (see CODE_OWNERS.txt) and other people doing work in the area your
  66 patch touches. If you are using Phabricator, add them to the `Reviewers` field
  67 when creating a review and if you are using `llvm-commits`, add them to the CC of
  68 your email.
  69
  70 A reviewer may request changes or ask questions during the review. If you are
  71 uncertain on how to provide test cases, documentation, etc., feel free to ask
  72 for guidance during the review. Please address the feedback and re-post an
  73 updated version of your patch. This cycle continues until all requests and comments
  74 have been addressed and a reviewer accepts the patch with a `Looks good to me` or `LGTM`.
  75 Once that is done the change can be committed. If you do not have commit
  76 access, please let people know during the review and someone should commit it
  77 on your behalf.
  78
  79 If you have received no comments on your patch for a week, you can request a
  80 review by 'ping'ing a patch by responding to the email thread containing the
  81 patch, or the Phabricator review with "Ping." The common courtesy 'ping' rate
  82 is once a week. Please remember that you are asking for valuable time from other
  83 professional developers.
  84
  85
  86 Helpful Information About LLVM
  87 ==============================
  88 :doc:`LLVM's documentation <index>` provides a wealth of information about LLVM's internals as
  89 well as various user guides. The pages listed below should provide a good overview
  90 of LLVM's high-level design, as well as its internals:
  91
  92 :doc:`GettingStarted`
  93    Discusses how to get up and running quickly with the LLVM infrastructure.
  94    Everything from unpacking and compilation of the distribution to execution
  95    of some tools.
  96
  97 :doc:`LangRef`
  98   Defines the LLVM intermediate representation.
  99
 100 :doc:`ProgrammersManual`
 101   Introduction to the general layout of the LLVM sourcebase, important classes
 102   and APIs, and some tips & tricks.
 103
 104 :ref:`index-subsystem-docs`
 105   A collection of pages documenting various subsystems of LLVM.
 106
 107 `LLVM for Grad Students`__
 108   This is an introduction to the LLVM infrastructure by Adrian Sampson. While it
 109   has been written for grad students, it provides  a good, compact overview of
 110   LLVM's architecture, LLVM's IR and how to write a new pass.
 111
 112   .. __: http://www.cs.cornell.edu/~asampson/blog/llvm.html
 113
 114 `Intro to LLVM`__
 115   Book chapter providing a compiler hacker's introduction to LLVM.
 116
 117   .. __: http://www.aosabook.org/en/llvm.html
 118
 119 .. _Developer's List (llvm-dev): http://lists.llvm.org/mailman/listinfo/llvm-dev
 120 .. _irc.oftc.net: irc://irc.oftc.net/llvm
 121 .. _beginner keyword: https://bugs.llvm.org/buglist.cgi?bug_status=NEW&bug_status=REOPENED&keywords=beginner%2C%20&keywords_type=allwords&list_id=130748&query_format=advanced&resolution=---
 122 .. _bug tracker: https://bugs.llvm.org
 123 .. _clang-format-diff.py: https://reviews.llvm.org/source/clang/browse/cfe/trunk/tools/clang-format/clang-format-diff.py
 124 .. _git-clang-format: https://reviews.llvm.org/source/clang/browse/cfe/trunk/tools/clang-format/git-clang-format
 125 .. _LLVM's Phabricator: https://reviews.llvm.org/
 126 .. _LLVM's Open Projects page: https://llvm.org/OpenProjects.html#what
 127 .. _LLVM Developer's mailing list: http://lists.llvm.org/mailman/listinfo/llvm-dev