forked from OSchip/llvm-project
205 lines
8.3 KiB
ReStructuredText
205 lines
8.3 KiB
ReStructuredText
==================================
|
|
Contributing to LLVM
|
|
==================================
|
|
|
|
|
|
Thank you for your interest in contributing to LLVM! There are multiple ways to
|
|
contribute, and we appreciate all contributions. In case you
|
|
have questions, you can either use the `Forum`_
|
|
or the #llvm channel on `irc.oftc.net`_.
|
|
|
|
If you want to contribute code, please familiarize yourself with the :doc:`DeveloperPolicy`.
|
|
|
|
.. contents::
|
|
:local:
|
|
|
|
|
|
Ways to Contribute
|
|
==================
|
|
|
|
Bug Reports
|
|
-----------
|
|
If you are working with LLVM and run into a bug, we definitely want to know
|
|
about it. Please let us know and follow the instructions in
|
|
:doc:`HowToSubmitABug` to create a bug report.
|
|
|
|
Bug Fixes
|
|
---------
|
|
If you are interested in contributing code to LLVM, bugs labeled with the
|
|
`good first issue`_ keyword in the `bug tracker`_ are a good way to get familiar with
|
|
the code base. If you are interested in fixing a bug please comment on it to
|
|
let people know you are working on it.
|
|
|
|
Then try to reproduce and fix the bug with upstream LLVM. Start by building
|
|
LLVM from source as described in :doc:`GettingStarted` and
|
|
use the built binaries to reproduce the failure described in the bug. Use
|
|
a debug build (`-DCMAKE_BUILD_TYPE=Debug`) or a build with assertions
|
|
(`-DLLVM_ENABLE_ASSERTIONS=On`, enabled for Debug builds).
|
|
|
|
Reporting a Security Issue
|
|
--------------------------
|
|
|
|
There is a separate process to submit security-related bugs, see :ref:`report-security-issue`.
|
|
|
|
Bigger Pieces of Work
|
|
---------------------
|
|
In case you are interested in taking on a bigger piece of work, a list of
|
|
interesting projects is maintained at the `LLVM's Open Projects page`_. In case
|
|
you are interested in working on any of these projects, please post on the
|
|
`Forum`_, so that we know the project is being worked on.
|
|
|
|
.. _submit_patch:
|
|
|
|
How to Submit a Patch
|
|
=====================
|
|
Once you have a patch ready, it is time to submit it. The patch should:
|
|
|
|
* include a small unit test
|
|
* conform to the :doc:`CodingStandards`. You can use the `clang-format-diff.py`_ or `git-clang-format`_ tools to automatically format your patch properly.
|
|
* not contain any unrelated changes
|
|
* be an isolated change. Independent changes should be submitted as separate patches as this makes reviewing easier.
|
|
* have a single commit (unless stacked on another Differential), up-to-date with the upstream ``origin/main`` branch, and don't have merges.
|
|
|
|
.. _format patches:
|
|
|
|
Before sending a patch for review, please also try to ensure it is
|
|
formatted properly. We use ``clang-format`` for this, which has git integration
|
|
through the ``git-clang-format`` script. On some systems, it may already be
|
|
installed (or be installable via your package manager). If so, you can simply
|
|
run it -- the following command will format only the code changed in the most
|
|
recent commit:
|
|
|
|
.. code-block:: console
|
|
|
|
% git clang-format HEAD~1
|
|
|
|
Note that this modifies the files, but doesn't commit them -- you'll likely want
|
|
to run
|
|
|
|
.. code-block:: console
|
|
|
|
% git commit --amend -a
|
|
|
|
in order to update the last commit with all pending changes.
|
|
|
|
.. note::
|
|
If you don't already have ``clang-format`` or ``git clang-format`` installed
|
|
on your system, the ``clang-format`` binary will be built alongside clang, and
|
|
the git integration can be run from
|
|
``clang/tools/clang-format/git-clang-format``.
|
|
|
|
We don't currently accept GitHub pull requests, and you'll need to send patches
|
|
via :ref:`Phabricator#phabricator-reviews <phabricator-reviews>`.
|
|
(We used to allow patches on the llvm-commits mailing list, but the mailing lists
|
|
have been deprecated.)
|
|
|
|
To make sure the right people see your patch, please select suitable reviewers
|
|
and add them to your patch when requesting a review. Suitable reviewers are the
|
|
code owner (see CODE_OWNERS.txt) and other people doing work in the area your
|
|
patch touches. If you are using Phabricator, add them to the `Reviewers` field
|
|
when creating a review and if you are using `llvm-commits`, add them to the CC of
|
|
your email.
|
|
|
|
A reviewer may request changes or ask questions during the review. If you are
|
|
uncertain on how to provide test cases, documentation, etc., feel free to ask
|
|
for guidance during the review. Please address the feedback and re-post an
|
|
updated version of your patch. This cycle continues until all requests and comments
|
|
have been addressed and a reviewer accepts the patch with a `Looks good to me` or `LGTM`.
|
|
Once that is done the change can be committed. If you do not have commit
|
|
access, please let people know during the review and someone should commit it
|
|
on your behalf.
|
|
|
|
If you have received no comments on your patch for a week, you can request a
|
|
review by 'ping'ing a patch by responding to the email thread containing the
|
|
patch, or the Phabricator review with "Ping." The common courtesy 'ping' rate
|
|
is once a week. Please remember that you are asking for valuable time from other
|
|
professional developers.
|
|
|
|
For more information on LLVM's code-review process, please see :doc:`CodeReview`.
|
|
|
|
.. _commit_from_git:
|
|
|
|
For developers to commit changes from Git
|
|
-----------------------------------------
|
|
|
|
Once a patch is reviewed, you should rebase it, re-test locally, and commit the
|
|
changes to LLVM's main branch. This is done using `git push` if you have the
|
|
required access rights. See `committing a change
|
|
<Phabricator.html#committing-a-change>`_ for Phabricator based commits or
|
|
`obtaining commit access <DeveloperPolicy.html#obtaining-commit-access>`_
|
|
for commit access.
|
|
|
|
Here is an example workflow using git. This workflow assumes you have an
|
|
accepted commit on the branch named `branch-with-change`.
|
|
|
|
.. code-block:: console
|
|
|
|
# Pull changes from the upstream main branch.
|
|
% git checkout main && git pull
|
|
# Rebase your change onto main.
|
|
% git rebase --onto main --root branch-with-change
|
|
# Rerun the appropriate tests if needed.
|
|
% ninja check-$whatever
|
|
# Check that the list of commits about to be pushed is correct.
|
|
% git log origin/main...HEAD --oneline
|
|
# Push to Github.
|
|
% git push origin HEAD:main
|
|
|
|
LLVM currently has a linear-history policy, which means that merge commits are
|
|
not allowed. The `llvm-project` repo on github is configured to reject pushes
|
|
that include merges, so the `git rebase` step above is required.
|
|
|
|
Please ask for help if you're having trouble with your particular git workflow.
|
|
|
|
.. _git_pre_push_hook:
|
|
|
|
Git pre-push hook
|
|
^^^^^^^^^^^^^^^^^
|
|
|
|
We include an optional pre-push hook that run some sanity checks on the revisions
|
|
you are about to push and ask confirmation if you push multiple commits at once.
|
|
You can set it up (on Unix systems) by running from the repository root:
|
|
|
|
.. code-block:: console
|
|
|
|
% ln -sf ../../llvm/utils/git/pre-push.py .git/hooks/pre-push
|
|
|
|
Helpful Information About LLVM
|
|
==============================
|
|
:doc:`LLVM's documentation <index>` provides a wealth of information about LLVM's internals as
|
|
well as various user guides. The pages listed below should provide a good overview
|
|
of LLVM's high-level design, as well as its internals:
|
|
|
|
:doc:`GettingStarted`
|
|
Discusses how to get up and running quickly with the LLVM infrastructure.
|
|
Everything from unpacking and compilation of the distribution to execution
|
|
of some tools.
|
|
|
|
:doc:`LangRef`
|
|
Defines the LLVM intermediate representation.
|
|
|
|
:doc:`ProgrammersManual`
|
|
Introduction to the general layout of the LLVM sourcebase, important classes
|
|
and APIs, and some tips & tricks.
|
|
|
|
`LLVM for Grad Students`__
|
|
This is an introduction to the LLVM infrastructure by Adrian Sampson. While it
|
|
has been written for grad students, it provides a good, compact overview of
|
|
LLVM's architecture, LLVM's IR and how to write a new pass.
|
|
|
|
.. __: http://www.cs.cornell.edu/~asampson/blog/llvm.html
|
|
|
|
`Intro to LLVM`__
|
|
Book chapter providing a compiler hacker's introduction to LLVM.
|
|
|
|
.. __: http://www.aosabook.org/en/llvm.html
|
|
|
|
.. _Forum: https://discourse.llvm.org
|
|
.. _irc.oftc.net: irc://irc.oftc.net/llvm
|
|
.. _good first issue: https://github.com/llvm/llvm-project/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22
|
|
.. _bug tracker: https://github.com/llvm/llvm-project/issues
|
|
.. _clang-format-diff.py: https://reviews.llvm.org/source/llvm-github/browse/main/clang/tools/clang-format/clang-format-diff.py
|
|
.. _git-clang-format: https://reviews.llvm.org/source/llvm-github/browse/main/clang/tools/clang-format/git-clang-format
|
|
.. _LLVM's Phabricator: https://reviews.llvm.org/
|
|
.. _LLVM's Open Projects page: https://llvm.org/OpenProjects.html#what
|