1536 lines · plain
1.. _developer_policy:2 3=====================4LLVM Developer Policy5=====================6 7.. contents::8 :local:9 10Introduction11============12 13This document contains the LLVM Developer Policy which defines the project's14policy towards developers and their contributions. The intent of this policy is15to eliminate miscommunication, rework, and confusion that might arise from the16distributed nature of LLVM's development. By stating the policy in clear terms,17we hope each developer can know ahead of time what to expect when making LLVM18contributions. This policy covers all llvm.org subprojects, including Clang,19LLDB, libc++, MLIR, etc.20 21The developer policy supports the following LLVM project objectives:22 23#. Attract both users and new contributors to the LLVM project.24 25#. Help people contribute to LLVM by documenting our development practices.26 27#. Maintain the stability, performance, and quality of the ``main`` branch.28 29#. Establish the project's :ref:`copyright, license, and patent30 policies <copyright-license-patents>` policies.31 32Developer Policies33==================34 35Communication Channels36----------------------37 38LLVM is a large project with many subcomponents, and it has a wide array of39communication channels that you can use to keep track of recent developments,40upcoming projects, new designs, enhancements, and other community business.41 42First and foremost is the `LLVM Discourse forums`_, which is the successor43to our former mailing lists (llvm-dev@, cfe-dev@, lldb-dev@, etc). This is44probably the most vital and active communication channel to our highly45distributed open source project. It enables long-form asynchronous text46communication, and this is where people tend to propose major changes or47propose new designs in the form of RFCs (Request For Comment), which are48described later. Please be aware that the Discourse forums are public and49archived, and that notices of confidentiality or non-disclosure cannot be50respected.51 52We accept code contributions as :ref:`GitHub Pull Requests <github-reviews>`.53Our project is generally too large to subscribe to all github notifications, so54if you want to be notified of pull requests affecting specific parts of the55code, you can join56one of the `pr-subscribers-* <https://github.com/orgs/llvm/teams?query=pr-subscribers>`_57GitHub teams. This `mapping <https://github.com/llvm/llvm-project/blob/main/.github/new-prs-labeler.yml>`_58documents the paths that trigger notifications for each of the listed teams.59 60Missing features and bugs are tracked through our `GitHub issue tracker61<https://github.com/llvm/llvm-project/issues>`_. You can subscribe for62notification for specific components by joining one of the `issue-subscribers-*63<https://github.com/orgs/llvm/teams?query=issue-subscribers>`_ teams. You may64also subscribe to the `llvm-bugs65<http://lists.llvm.org/mailman/listinfo/llvm-bugs>`_ email list to subscribe to66the firehose of all issue notifications, which some community members use to67perform custom filtering.68 69Beyond the asynchronous written communication channels, LLVM has a Discord70server for real-time chat communication, as well as a community calendar with71many regular workgroup video calls and office hours. See :doc:`GettingInvolved`72for more information on other ways to engage with the community.73 74.. _patch:75 76Making and Submitting a Patch77-----------------------------78 79Patches are submitted to GitHub and reviewed using Pull Requests. Follow the80:ref:`Getting Started Guide <sources>` to check out sources, make a patch, and81then follow the :ref:`GitHub Pull Request <github-reviews>` guide to upload a82pull request.83 84Here are some tips to enable a successful code review:85 86* :ref:`Include a test <include a testcase>`. This tends to be one of the first87 things a reviewer will ask for and look at to understand what a new patch88 does.89 90* Identify 2-3 individuals to review the patch. Look through the relevant91 :ref:`Maintainers` file or browse git blame for likely stakeholders for the92 code you want to modify, and add ``@username`` to a PR comment to notify them93 of your PR if you are unable to add reviewers yourself due to GitHub permissions.94 95* To avoid precommit CI failures due to merge conflicts, base your patches on a96 recent commit from ``main``. If you want to make changes to a release branch,97 land a change in ``main`` first and then follow the98 :ref:`backporting instructions <backporting>`.99 100See :doc:`CodeReview` for more info on what to expect.101 102When submitting patches, please do not add confidentiality or non-disclosure103notices to the patches themselves. These notices conflict with the LLVM104licensing terms and may result in your contribution being excluded.105 106.. _github-email-address:107 108Email Addresses109---------------110 111The LLVM project uses email to communicate to contributors outside of the112GitHub platform about their past contributions. Primarily, our buildbot113infrastructure uses emails to contact contributors about build and test114failures.115 116Therefore, the LLVM community requires contributors to have a public email117address associated with their GitHub commits, so please ensure that "Keep my118email addresses private" is disabled in your `account settings119<https://github.com/settings/emails>`_. There are many free email forwarding120services available if you wish to keep your identity private.121 122.. _code review:123 124Code Reviews125------------126 127LLVM uses code review, which is a generally accepted software engineering best128practice for maintaining high code quality. Please see :doc:`CodeReview` for129more information on LLVM's code review process.130 131.. _maintainers:132 133Maintainers134-----------135 136The LLVM Project aims to evolve features quickly while continually being in a137release-ready state. In order to accomplish this, the project needs volunteers138willing to do the less glamorous work to ensure we produce robust, high-quality139products.140 141Maintainers are those volunteers; they are regular contributors who volunteer142to take on additional community responsibilities beyond code contributions.143Community members can find active and inactive maintainers for a project in the144``Maintainers.rst`` file at the root directory of the individual project.145 146Maintainers are volunteering to take on the following shared responsibilities147within an area of a project:148 149* ensure that commits receive high-quality review, either by the maintainer150 or by someone else,151* help to confirm and comment on issues,152* mediate code review disagreements through collaboration with other153 maintainers (and other reviewers) to come to a consensus on how best to154 proceed with disputed changes,155* actively engage with relevant RFCs,156* aid release managers with backporting and other release-related157 activities,158* be a point of contact for contributors who need help (answering questions159 on Discord/Discourse or holding office hours).160 161Each top-level project in the monorepo will specify one or more162lead maintainers who are responsible for ensuring community needs are163met for that project. This role is like any other maintainer role,164except the responsibilities span the project rather than a limited area165within the project. If you cannot reach a maintainer or don't know which166maintainer to reach out to, a lead maintainer is always a good choice167to reach out to. If a project has no active lead maintainers, it may be a168reasonable candidate for removal from the monorepo. A discussion should be169started on Discourse to find a new, active lead maintainer or whether the170project should be discontinued.171 172All contributors with commit access to the LLVM Project are eligible to be a173maintainer. However, we are looking for people who can commit to:174 175* engaging in their responsibilities the majority of the days in a month,176* ensuring that they, and the community members they interact with, abide by the177 :ref:`LLVM Community Code of Conduct`, and178* performing these duties for at least three months.179 180We recognize that priorities shift, job changes happen, burnout is real,181extended vacations are a blessing, and people's lives are generally complex.182Therefore, we want as little friction as possible for someone to become a183maintainer or to step down as a maintainer.184 185*To become a new maintainer*, you can volunteer yourself by posting a PR which186adds yourself to the area(s) you are volunteering for. Alternatively, an187existing maintainer can nominate you by posting a PR, but the nominee must188explicitly accept the PR so that it's clear they agree to volunteer within the189proposed area(s). The PR will be accepted so long as at least one maintainer in190the same project vouches for their ability to perform the responsibilities and191there are no explicit objections raised by the community.192 193*To step down as a maintainer*, you can move your name to the "inactive194maintainers" section of the ``Maintainers.rst`` file for the project, or remove195your name entirely; no PR review is necessary. Additionally, any maintainer who196has not been actively performing their responsibilities over an extended period197of time can be moved to the "inactive maintainers" section by another active198maintainer within that project with agreement from one other active maintainer199within that project. If there is only one active maintainer for a project,200please post on Discourse to solicit wider community feedback about the removal201and future direction for the project. However, please discuss the situation202with the inactive maintainer before such removal to avoid accidental203miscommunications. If the inactive maintainer is unreachable, no discussion204with them is required. Stepping down or being removed as a maintainer is normal205and does not prevent someone from resuming their activities as a maintainer in206the future.207 208*To resume activities as a maintainer*, you can post a PR moving your name from209the "inactive maintainers" section of the ``Maintainers.rst`` file to the210active maintainers list. Because the volunteer was already previously accepted,211they will be re-accepted so long as at least one maintainer in the same project212approves the PR and there are no explicit objections raised by the community.213 214.. _include a testcase:215 216Test Cases217----------218 219Developers are required to create test cases for any bugs fixed and any new220features added. Some tips for getting your testcase approved:221 222* All feature and regression test cases are added to the ``test`` subdirectory223 of each LLVM subproject, i.e. ``llvm-project/llvm/test`` for LLVM itself. The224 appropriate sub-directory should be selected (see the225 :doc:`Testing Guide <TestingGuide>` for details).226 227* We prefer that functional changes are tested using ``FileCheck`` and the tool228 that fits most closely with the code being modified. For example, ``opt`` is229 used to test IR transformations, ``llc`` for backend changes, and ``clang``230 for frontend changes. Some components have scripts for generating and231 updating golden tests in the ``utils/`` subproject directory, i.e.232 `mlir/utils/generate-test-checks.py <https://github.com/llvm/llvm-project/blob/main/mlir/utils/generate-test-checks.py>`_233 and `llvm/utils/update_llc_test_checks.py <https://github.com/llvm/llvm-project/blob/main/llvm/utils/update_llc_test_checks.py>`_234 235* Some subprojects such as ``clang`` and ``clangd`` have project specific236 testing tools, like the ``clang -verify`` flag (`docs237 <https://clang.llvm.org/docs/InternalsManual.html#verifying-diagnostics>`_)238 and the ``clangd -lit-test``239 flag, which are preferred over ``FileCheck``.240 241* Changes to libraries, such as Support, which are not directly observable242 through tool invocations, are often best tested with unit tests. Unit tests243 are located under the ``unittests`` subdirectory of each subproject.244 245* Test cases should be targeted. Large inputs exhibiting bugs should be reduced246 with tools like ``llvm-reduce`` before committing them to the suite. It is not247 acceptable to place an entire failing program into ``llvm/test`` as this248 creates a *time-to-test* burden on all developers. Please keep them short.249 250* Avoid adding links to resources that are not available to the entire251 community, such as links to private bug trackers, internal corporate252 documentation, etc. Instead, add sufficient comments to the test to provide253 the context behind such links.254 255As a project, we prefer to separate tests into small in-tree tests, and large256out-of-tree integration tests. More extensive integration test cases (e.g.,257entire applications, benchmarks, etc) should be added to the `llvm-test-suite258<https://github.com/llvm/llvm-test-suite>`_ repository. The259``llvm-test-suite`` repository is for integration and application testing260(correctness, performance, etc) testing, not feature or regression testing. It261also serves to separate out third party code that falls under a different262license.263 264Release Notes265-------------266 267Many projects in LLVM communicate important changes to users through release268notes, typically found in ``docs/ReleaseNotes.rst`` for the project. Changes to269a project that are user-facing, or that users may wish to know about, should be270added to the project's release notes at the author's or code reviewer's271discretion, preferably as part of the commit landing the changes. Examples of272changes that would typically warrant adding a release note (this list is not273exhaustive):274 275* Adding, removing, or modifying command-line options.276* Adding, removing, or regrouping a diagnostic.277* Fixing a bug that potentially has significant user-facing impact (please link278 to the issue fixed in the bug database).279* Adding or removing optimizations that have widespread impact or enables new280 programming paradigms.281* Modifying a C stable API.282* Notifying users about a potentially disruptive change expected to be made in283 a future release, such as removal of a deprecated feature. In this case, the284 release note should be added to a ``Potentially Breaking Changes`` section of285 the notes with sufficient information and examples to demonstrate the286 potential disruption. Additionally, any new entries to this section should be287 announced in the `Announcements <https://discourse.llvm.org/c/announce/>`_288 channel on Discourse. See :ref:`breaking` for more details.289 290Code reviewers are encouraged to request a release note if they think one is291warranted when performing a code review.292 293Quality294-------295 296The minimum quality standards that any change must satisfy before being297committed to the main development branch are:298 299#. Code must adhere to the :doc:`LLVM Coding Standards <CodingStandards>`.300 301#. Code must compile cleanly (no errors, no warnings) on at least one platform.302 303#. Bug fixes and new features should `include a testcase`_ so we know if the304 fix/feature ever regresses in the future.305 306#. Pull requests should build and pass premerge checks. For first-time307 contributors, this will require an initial cursory review to run the checks.308 309#. Ensure that links in source code and test files point to publicly available310 resources and are used primarily to add additional information rather than to311 supply critical context. The surrounding comments should be sufficient to312 provide the context behind such links.313 314Additionally, the committer is responsible for addressing any problems found in315the future that the change is responsible for. For example:316 317* The code needs to compile cleanly and pass tests on all stable `LLVM318 buildbots <https://lab.llvm.org/buildbot/>`_.319 320* The changes should not cause any correctness regressions in the321 `llvm-test-suite <https://github.com/llvm/llvm-test-suite>`_322 and must not cause any major performance regressions.323 324* The change set should not cause performance or correctness regressions for the325 LLVM tools. See `llvm-compile-time-tracker.com <https://llvm-compile-time-tracker.com>`_326 327* The changes should not cause performance or correctness regressions in code328 compiled by LLVM on all applicable targets.329 330* You are expected to address any `GitHub Issues331 <https://github.com/llvm/llvm-project/issues>`_ that result from your change.332 333Our build bots and `nightly testing infrastructure334<https://llvm.org/docs/lnt/intro.html>`_ find many of these issues. Build bots335will directly email you if a group of commits that included yours caused a336failure. You are expected to check the build bot messages to see if they are337your fault and, if so, fix the breakage. However, keep in mind that if you338receive such an email, it is highly likely that your change is not at fault.339Changes are batched together precisely because these tests are generally too340expensive to run continuously for every change.341 342Commits that violate these quality standards may be reverted (see below). This343is necessary when the change blocks other developers from making progress. The344developer is welcome to re-commit the change after the problem has been fixed.345 346 347.. _commit messages:348 349Commit messages350---------------351 352Although we don't enforce the format of commit messages, we prefer that353you follow these guidelines to help review, search in logs, email formatting354and so on. These guidelines are very similar to rules used by other open source355projects.356 357Commit messages should communicate briefly what the change does, but they358should really emphasize why a change is being made and provide useful context.359Commit messages should be thoughtfully written and specific, rather than vague.360For example, "bits were not set right" will leave the reviewer wondering about361which bits, and why they weren't right, while "Correctly set overflow bits in362TargetInfo" conveys almost all there is to the change.363 364Below are some guidelines about the format of the message itself:365 366* Separate the commit message into title and body separated by a blank line.367 368* If you're not the original author, ensure the 'Author' property of the commit is369 set to the original author and the 'Committer' property is set to yourself.370 You can use a command similar to371 ``git commit --amend --author="John Doe <jdoe@llvm.org>"`` to correct the372 author property if it is incorrect. See `Attribution of Changes`_ for more373 information including the method we used for attribution before the project374 migrated to git.375 376 In the rare situation where there are multiple authors, please use the `git377 tag 'Co-authored-by:' to list the additional authors378 <https://github.blog/2018-01-29-commit-together-with-co-authors/>`_.379 380* The title should be concise. Because all commits are emailed to the list with381 the first line as the subject, long titles are frowned upon. Short titles382 also look better in `git log`.383 384* When the changes are restricted to a specific part of the code (e.g. a385 back-end or optimization pass), it is customary to add a tag to the386 beginning of the line in square brackets. For example, "[SCEV] ..."387 or "[OpenMP] ...". This helps email filters and searches for post-commit388 reviews.389 390* The body should be concise, but explanatory, including a complete391 rationale. Unless it is required to understand the change, examples,392 code snippets and gory details should be left to bug comments, web393 review or the mailing list.394 395* Text formatting and spelling should follow the same rules as documentation396 and in-code comments, ex. capitalization, full stop, etc.397 398* If the commit is a bug fix on top of another recently committed patch, or a399 revert or reapply of a patch, include the git commit hash of the prior400 related commit. This could be as simple as "Revert commit NNNN because it401 caused issue #".402 403* If the patch has been reviewed, add a link to its review page, as shown404 `here <https://www.llvm.org/docs/Phabricator.html#committing-a-change>`__.405 If the patch fixes a bug in GitHub Issues, we encourage adding a reference to406 the issue being closed, as described407 `here <https://llvm.org/docs/BugLifeCycle.html#resolving-closing-bugs>`__.408 409* It is also acceptable to add other metadata to the commit message to automate410 processes, including for downstream consumers. This metadata can include411 links to resources that are not available to the entire community. However,412 such links and/or metadata should not be used in place of making the commit413 message self-explanatory. Note that such non-public links should not be414 included in the submitted code.415 416* Avoid 'tagging' someone's username in your commits and PR descriptions417 (e.g., `@<someUser>`), doing so results in that account receiving a notification418 every time the commit is cherry-picked and/or pushed to a fork.419 420LLVM uses a squash workflow for pull requests, so as the pull request evolves421during review, it's important to update the pull request description over the422course of a review. GitHub uses the initial commit message to create the pull423request description, but it ignores all subsequent commit messages. Authors and424reviewers should make a final editing pass over the squashed commit description when425squashing and merging PRs.426 427For minor violations of these recommendations, the community normally favors428reminding the contributor of this policy over reverting.429 430.. _revert_policy:431 432Patch reversion policy433----------------------434 435As a community, we strongly value having the tip of tree in a good state while436allowing rapid iterative development. As such, we tend to make much heavier437use of reverts to keep the tree healthy than some other open source projects,438and our norms are a bit different.439 440How should you respond if someone reverted your change?441 442* Remember, it is normal and healthy to have patches reverted. Having a patch443 reverted does not necessarily mean you did anything wrong.444* We encourage explicitly thanking the person who reverted the patch for doing445 the task on your behalf.446* If you need more information to address the problem, please follow up in the447 original commit thread with the reverting patch author.448 449When should you revert your own change?450 451* Any time you learn of a serious problem with a change, you should revert it.452 We strongly encourage "revert to green" as opposed to "fixing forward". We453 encourage reverting first, investigating offline, and then reapplying the454 fixed patch - possibly after another round of review if warranted.455* If you break a buildbot in a way which can't be quickly fixed, please revert.456* If a test case that demonstrates a problem is reported in the commit thread,457 please revert and investigate offline.458* If you receive substantial :ref:`post-commit review <post_commit_review>`459 feedback, please revert and address said feedback before recommitting.460 (Possibly after another round of review.)461* If you are asked to revert by another contributor, please revert and discuss462 the merits of the request offline (unless doing so would further destabilize463 tip of tree).464 465When should you revert someone else's change?466 467* In general, if the author themselves would revert the change per these468 guidelines, we encourage other contributors to do so as a courtesy to the469 author. This is one of the major cases where our norms differ from others;470 we generally consider reverting a normal part of development. We don't471 expect contributors to be always available, and the assurance that a472 problematic patch will be reverted and we can return to it at our next473 opportunity enables this.474 475What are the expectations around a revert?476 477* Use your best judgment. If you're uncertain, please start an email on478 the commit thread asking for assistance. We aren't trying to enumerate479 every case, but rather give a set of guidelines.480* You should be sure that reverting the change improves the stability of tip481 of tree. Sometimes, reverting one change in a series can worsen things482 instead of improving them. We expect reasonable judgment to ensure that483 the proper patch or set of patches is being reverted.484* The commit message for the reverting commit should explain why patch485 is being reverted.486* It is customary to respond to the original commit email mentioning the487 revert. This serves as both a notice to the original author that their488 patch was reverted, and helps others following llvm-commits track context.489* Ideally, you should have a publicly reproducible test case ready to share.490 Where possible, we encourage sharing of test cases in commit threads, or491 in PRs. We encourage the reverter to minimize the test case and to prune492 dependencies where practical. This even applies when reverting your own493 patch; documenting the reasons for others who might be following along494 is critical.495* It is not considered reasonable to revert without at least the promise to496 provide a means for the patch author to debug the root issue. If a situation497 arises where a public reproducer can not be shared for some reason (e.g.498 requires hardware patch author doesn't have access to, sharp regression in499 compile time of internal workload, etc.), the reverter is expected to be500 proactive about working with the patch author to debug and test candidate501 patches.502* Reverts should be reasonably timely. A change submitted two hours ago503 can be reverted without prior discussion. A change submitted two years ago504 should not be. Where exactly the transition point is is hard to say, but505 it's probably in the handful of days in tree territory. If you are unsure,506 we encourage you to reply to the commit thread, give the author a bit to507 respond, and then proceed with the revert if the author doesn't seem to be508 actively responding.509* When re-applying a reverted patch, the commit message should be updated to510 indicate the problem that was addressed and how it was addressed.511 512.. _obtaining_commit_access:513 514Obtaining Commit Access515-----------------------516 517Once you have 3 or more merged pull requests, you may use `this link518<https://github.com/llvm/llvm-project/issues/new?title=Request%20Commit%20Access%20For%20%3Cuser%3E&body=%23%23%23%20Why%20Are%20you%20requesting%20commit%20access%20?>`_519to file an issue and request commit access. Replace the <user> string in the title520with your github username, and explain why you are requesting commit access in521the issue description. Once the issue is created, you will need to get two522current contributors to support your request before commit access will be granted.523 524Reviewers of your committed patches will automatically be CCed upon creating the issue.525Most commonly these reviewers will provide the necessary approval, but approvals526from other LLVM committers are also acceptable. Those reviewing the application are527confirming that you have indeed had three patches committed, and that based on interactions528on those reviews and elsewhere in the LLVM community they have no concern about you529adhering to our Developer Policy and Code of Conduct. Reviewers should clearly state their530reasoning for accepting or rejecting the request, and finish with a clear statement such531as "I approve of this request", "LGTM", or "I do not approve of this request".532 533 534If approved, a GitHub invitation will be sent to your535GitHub account. In case you don't get notification from GitHub, go to536`Invitation Link <https://github.com/orgs/llvm/invitation>`_ directly. Once537you accept the invitation, you'll get commit access.538 539Prior to obtaining commit access, it is common practice to request that540someone with commit access commits on your behalf. When doing so, please541provide the name and email address you would like to use in the Author542property of the commit.543 544For external tracking purposes, committed changes are automatically reflected on545a commits mailing list soon after the commit lands (e.g.546llvm-commits@lists.llvm.org). Note that these mailing lists are moderated, and547it is not unusual for a large commit to require a moderator to approve the548email, so do not be concerned if a commit does not immediately appear in the549archives.550 551If you have recently been granted commit access, these policies apply:552 553#. You are granted *commit-after-approval* to all parts of LLVM. For554 information on how to get approval for a patch, please see :doc:`CodeReview`.555 When approved, you may commit it yourself.556 557#. You are allowed to commit patches without approval which you think are558 obvious. This is clearly a subjective decision --- we simply expect you to559 use good judgement. Examples include: fixing build breakage, reverting560 obviously broken patches, documentation/comment changes, any other minor561 changes. Avoid committing formatting- or whitespace-only changes outside of562 code you plan to make subsequent changes to. Also, try to separate563 formatting or whitespace changes from functional changes, either by564 correcting the format first (ideally) or afterward. Such changes should be565 highly localized and the commit message should clearly state that the commit566 is not intended to change functionality, usually by stating it is567 :ref:`NFC <nfc>`.568 569#. You are allowed to commit patches without approval to those portions of LLVM570 that you have contributed or maintain (i.e., have been assigned571 responsibility for), with the proviso that such commits must not break the572 build. This is a "trust but verify" policy, and commits of this nature are573 reviewed after they are committed.574 575#. Multiple violations of these policies or a single egregious violation may576 cause commit access to be revoked.577 578In any case, your changes are still subject to `code review`_ (either before or579after they are committed, depending on the nature of the change). You are580encouraged to review other peoples' patches as well, but you aren't required581to do so.582 583Obtaining Other Access or Permissions584-------------------------------------585 586To obtain access other than commit access, you can raise an issue like the one587for obtaining commit access. However, instead of including PRs you have authored,588include evidence of your need for the type of access you want.589 590For example, if you are helping to triage issues and want the ability to add591labels, include links to issues you have triaged previously and explain how592having this ability would help that work.593 594.. _discuss the change/gather consensus:595 596Proposing Major Changes (RFCs)597------------------------------598 599LLVM is a large community with many stakeholders, and before landing any major600change, it is important to discuss the design of a change publicly with the601community. This is done by posting a Request For Comments (RFC) on the `LLVM602Discourse forums`_.603 604The design of LLVM is carefully controlled to ensure that all the pieces fit605together well and are as consistent as possible. If you plan to make a major606change to the way LLVM works or want to add a major new extension, it is a good607idea to get consensus with the development community before you invest608significant effort in an implementation. Prototype implementations, however, can609often be helpful in making design discussions more concrete by demonstrating610what is possible.611 612These are some suggestions for how to get a major change accepted:613 614* Make it targeted, and avoid touching components irrelevant to the task.615 616* Explain how the change improves LLVM for other stakeholders rather than617 focusing on your specific use case.618 619* As discussion evolves, periodically summarize the current state of the620 discussion and clearly separate points where consensus seems to emerge from621 those where further discussion is necessary.622 623* Compilers are foundational infrastructure, so there is a high quality bar,624 and the burden of proof is on the proposer. If reviewers repeatedly ask for625 an unreasonable amount of evidence or data, proposal authors can escalate to626 the area team to resolve disagreements.627 628After posting a major proposal, it is common to receive lots of conflicting629feedback from different parties, or no feedback at all, leaving authors without630clear next steps. As a community, we are aiming for `"rough consensus"631<https://en.wikipedia.org/wiki/Rough_consensus>`_, similar in spirit to what is632described in `IETF RFC7282 <https://datatracker.ietf.org/doc/html/rfc7282>`_.633This requires considering and addressing all of the objections to the RFC, and634confirming that we can all live with the tradeoffs embodied in the proposal.635 636The LLVM Area Teams (defined in `LP0004637<https://github.com/llvm/llvm-www/blob/main/proposals/LP0004-project-governance.md>`_)638are responsible for facilitating project decision making. In cases where there639isn't obvious agreement, area teams should step in to restate their perceived640consensus. In cases of deeper disagreement, area teams should try to identify641the next steps for the proposal, such as gathering more data, changing the642proposal, or rejecting it outright. They can also act as moderators by643scheduling calls for participants to speak directly to resolve disagreements,644subject to normal :ref:`Code of Conduct <LLVM Community Code of Conduct>`645guidelines.646 647Once the design of the new feature is finalized, the work itself should be done648as a series of `incremental changes`_, not as a long-term development branch.649 650.. _incremental changes:651 652Incremental Development653-----------------------654 655In the LLVM project, we prefer the incremental development approach, where656significant changes are developed in-tree incrementally. The alternative657approach of implementing features in long-lived development branches or forks658is discouraged, although we have accepted features developed this way in the659past. Long-term development branches have a number of drawbacks:660 661#. Branches must have mainline merged into them periodically. If the branch662 development and mainline development occur in the same pieces of code,663 resolving merge conflicts can take a lot of time.664 665#. Other people in the community tend to ignore work on branches.666 667#. Huge changes (produced when a branch is merged back onto mainline) are668 extremely difficult to `code review`_.669 670#. Branches are not routinely tested by our nightly tester infrastructure.671 672#. Changes developed as monolithic large changes often don't work until the673 entire set of changes is done. Breaking it down into a set of smaller674 changes increases the odds that any of the work will be committed to the main675 repository.676 677To address these problems, LLVM uses an incremental development style and we678require contributors to follow this practice when making a large/invasive679change. Some tips:680 681* Large/invasive changes usually have a number of secondary changes that are682 required before the big change can be made (e.g. API cleanup, etc). These683 sorts of changes can often be done before the major change is done,684 independently of that work.685 686* The remaining inter-related work should be decomposed into unrelated sets of687 changes if possible. Once this is done, define the first increment and get688 consensus on what the end goal of the change is.689 690* Each change in the set can be stand alone (e.g. to fix a bug), or part of a691 planned series of changes that works towards the development goal.692 693* Each change should be kept as small as possible. This simplifies your work694 (into a logical progression), simplifies code review and reduces the chance695 that you will get negative feedback on the change. Small increments also696 facilitate the maintenance of a high quality code base.697 698* Often, an independent precursor to a big change is to add a new API and slowly699 migrate clients to use the new API. Each change to use the new API is often700 "obvious" and can be committed without review. Once the new API is in place701 and used, it is much easier to replace the underlying implementation of the702 API. This implementation change is logically separate from the API703 change.704 705If you are interested in making a large change, and this scares you, please make706sure to first `discuss the change/gather consensus`_ then ask about the best way707to go about making the change.708 709.. _breaking:710 711Making Potentially Breaking Changes712-----------------------------------713 714Please help notify users and vendors of potential disruptions when upgrading to715a newer version of a tool. For example, deprecating a feature that is expected716to be removed in the future, removing an already-deprecated feature, upgrading717a diagnostic from a warning to an error, switching important default behavior,718or any other potentially disruptive situation thought to be worth raising719awareness of. For such changes, the following should be done:720 721* When performing the code review for the change, please add any applicable722 "vendors" github team to the review for their awareness. The purpose of these723 groups is to give vendors early notice that potentially disruptive changes724 are being considered but have not yet been accepted. Vendors can give early725 testing feedback on the changes to alert us to unacceptable breakages. The726 current list of vendor groups is:727 728 * `Clang vendors <https://github.com/orgs/llvm/teams/clang-vendors>`_729 * `libc++ vendors <https://github.com/orgs/llvm/teams/libcxx-vendors>`_730 731 People interested in joining the vendors group can do so by clicking the732 "Join team" button on the linked github pages above.733 734* When committing the change to the repository, add appropriate information735 about the potentially breaking changes to the ``Potentially Breaking Changes``736 section of the project's release notes. The release note should have737 information about what the change is, what is potentially disruptive about738 it, as well as any code examples, links, and motivation that is appropriate739 to share with users. This helps users to learn about potential issues with740 upgrading to that release.741 742* After the change has been committed to the repository, the potentially743 disruptive changes described in the release notes should be posted to the744 `Announcements <https://discourse.llvm.org/c/announce/>`_ channel on745 Discourse. The post should be tagged with the ``potentially-breaking`` label746 and a label specific to the project (such as ``clang``, ``llvm``, etc). This747 is another mechanism by which we can give pre-release notice to users about748 potentially disruptive changes. It is a lower-traffic alternative to the749 joining "vendors" group. To automatically be notified of new announcements750 with the ``potentially-breaking`` label, go to your user preferences page in751 Discourse, and add the label to one of the watch categories under752 ``Notifications->Tags``.753 754Attribution of Changes755----------------------756 757When contributors submit a patch to an LLVM project, other developers with758commit access may commit it for the author once appropriate (based on the759progression of code review, etc.). When doing so, it is important to retain760correct attribution of contributions to their contributors. However, we do not761want the source code to be littered with random attributions "this code written762by J. Random Hacker" (this is noisy and distracting). In practice, the revision763control system keeps a perfect history of who changed what, and the CREDITS.txt764file describes higher-level contributions. If you commit a patch for someone765else, please follow the attribution of changes in the simple manner as outlined766by the `commit messages`_ section. Overall, please do not add contributor names767to the source code.768 769Also, don't commit patches authored by others unless they have submitted the770patch to the project or you have been authorized to submit them on their behalf771(you work together and your company authorized you to contribute the patches,772etc.). The author should first submit them to the relevant project's commit773list, development list, or LLVM bug tracker component. If someone sends you774a patch privately, encourage them to submit it to the appropriate list first.775 776Our previous version control system (subversion) did not distinguish between the777author and the committer like git does. As such, older commits used a different778attribution mechanism. The previous method was to include "Patch by John Doe."779in a separate line of the commit message and there are automated processes that780rely on this format.781 782Bans783----784 785The goal of a ban is to protect people in the community from having to interact786with people who are consistently not respecting the787:ref:`LLVM Community Code of Conduct` in LLVM project spaces. Contributions of788any variety (pull requests, issue reports, forum posts, etc.) require789interacting with the community. Therefore, we do not accept any form of direct790contribution from a banned individual.791 792Indirect contributions are permissible only by someone taking full ownership of793such a contribution and they are responsible for all related interactions with794the community regarding that contribution.795 796Trying to evade a non-permanent ban results in getting banned permanently.797 798When in doubt how to act in a specific instance, please reach out to799conduct@llvm.org for advice.800 801 802.. _IR backwards compatibility:803 804IR Backwards Compatibility805--------------------------806 807When the IR format has to be changed, keep in mind that we try to maintain some808backwards compatibility. The rules are intended as a balance between convenience809for llvm users and not imposing a big burden on llvm developers:810 811* The textual format is not backwards compatible. We don't change it too often,812 but there are no specific promises.813 814* Additions and changes to the IR should be reflected in815 ``test/Bitcode/compatibility.ll``.816 817* The current LLVM version supports loading any bitcode since version 3.0.818 819* After each X.Y release, ``compatibility.ll`` must be copied to820 ``compatibility-X.Y.ll``. The corresponding bitcode file should be assembled821 using the X.Y build and committed as ``compatibility-X.Y.ll.bc``.822 823* Newer releases can ignore features from older releases, but they cannot824 miscompile them. For example, if nsw is ever replaced with something else,825 dropping it would be a valid way to upgrade the IR.826 827* Debug metadata is special in that it is currently dropped during upgrades.828 829* Non-debug metadata is defined to be safe to drop, so a valid way to upgrade830 it is to drop it. That is not very user friendly and a bit more effort is831 expected, but no promises are made.832 833C API Changes834-------------835 836* Stability Guarantees: The C API is, in general, a "best effort" for stability.837 This means that we make every attempt to keep the C API stable, but that838 stability will be limited by the abstractness of the interface and the839 stability of the C++ API that it wraps. In practice, this means that things840 like "create debug info" or "create this type of instruction" are likely to be841 less stable than "take this IR file and JIT it for my current machine".842 843* Release stability: We won't break the C API on the release branch with patches844 that go on that branch, with the exception that we will fix an unintentional845 C API break that will keep the release consistent with both the previous and846 next release.847 848* Testing: Patches to the C API are expected to come with tests just like any849 other patch.850 851* Including new things into the API: If an LLVM subcomponent has a C API already852 included, then expanding that C API is acceptable. Adding C API for853 subcomponents that don't currently have one needs to be discussed on the854 `LLVM Discourse forums`_ for design and maintainability feedback prior to implementation.855 856* Documentation: Any changes to the C API are required to be documented in the857 release notes so that it's clear to external users who do not follow the858 project how the C API is changing and evolving.859 860.. _toolchain:861 862Updating Toolchain Requirements863-------------------------------864 865We intend to require newer toolchains as time goes by. This means LLVM's866codebase can use newer versions of C++ as they get standardized. Requiring newer867toolchains to build LLVM can be painful for those building LLVM; therefore, it868will only be done through the following process:869 870 * It is a general goal to support LLVM and GCC versions from the last 3 years871 at a minimum. This time-based guideline is not strict: we may support much872 older compilers, or decide to support fewer versions.873 874 * An RFC is sent to the `LLVM Discourse forums`_875 876 - Detail upsides of the version increase (e.g. which newer C++ language or877 library features LLVM should use; avoid miscompiles in particular compiler878 versions, etc).879 - Detail downsides on important platforms (e.g. Ubuntu LTS status).880 881 * Once the RFC reaches consensus, update the CMake toolchain version checks as882 well as the :doc:`getting started<GettingStarted>` guide. This provides a883 softer transition path for developers compiling LLVM, because the884 error can be turned into a warning using a CMake flag. This is an important885 step: LLVM still doesn't have code which requires the new toolchains, but it886 soon will. If you compile LLVM but don't read the forums, we should887 tell you!888 889 * Ensure that at least one LLVM release has had this soft-error. Not all890 developers compile LLVM top-of-tree. These release-bound developers should891 also be told about upcoming changes.892 893 * Turn the soft-error into a hard-error after said LLVM release has branched.894 895 * Update the :doc:`coding standards<CodingStandards>` to allow the new896 features we've explicitly approved in the RFC.897 898 * Start using the new features in LLVM's codebase.899 900Here's a `sample RFC901<https://discourse.llvm.org/t/rfc-migrating-past-c-11/50943>`_ and the902`corresponding change <https://reviews.llvm.org/D57264>`_.903 904.. _ci-usage:905 906Working with the CI system907--------------------------908 909The main continuous integration (CI) tool for the LLVM project is the910`LLVM Buildbot <https://lab.llvm.org/buildbot/>`_. It uses different *builders*911to cover a wide variety of sub-projects and configurations. The builds are912executed on different *workers*. Builders and workers are configured and913provided by community members.914 915The Buildbot tracks the commits on the main branch and the release branches.916This means that patches are built and tested after they are merged to the these917branches (aka post-merge testing). This also means it's okay to break the build918occasionally, as it's unreasonable to expect contributors to build and test919their patch with every possible configuration.920 921*If your commit broke the build:*922 923* Fix the build as soon as possible as this might block other contributors or924 downstream users.925* If you need more time to analyze and fix the bug, please revert your change to926 unblock others.927 928*If someone else broke the build and this blocks your work*929 930* Comment on the code review in `GitHub <https://github.com/llvm/llvm-project/pulls>`_931 (if available) or email the author, explain the problem and how this impacts932 you. Add a link to the broken build and the error message so folks can933 understand the problem.934* Revert the commit if this blocks your work, see revert_policy_ .935 936*If a build/worker is permanently broken*937 938* 1st step: contact the owner of the worker. You can find the name and contact939 information for the *Admin* of worker on the page of the build in the940 *Worker* tab:941 942 .. image:: buildbot_worker_contact.png943 944* 2nd step: If the owner does not respond or fix the worker, please escalate945 to Galina Kostanova, the maintainer of the BuildBot master.946* 3rd step: If Galina could not help you, please escalate to the947 `Infrastructure Working Group <mailto:iwg@llvm.org>`_.948 949.. _new-llvm-components:950 951Introducing New Components into LLVM952====================================953 954The LLVM community is a vibrant and exciting place to be, and we look to be955inclusive of new projects and foster new communities, and increase956collaboration across industry and academia.957 958That said, we need to strike a balance between being inclusive of new ideas and959people and the cost of ongoing maintenance that new code requires. As such, we960have a general :doc:`support policy<SupportPolicy>` for introducing major new961components into the LLVM world, depending on the degree of detail and962responsibility required. *Core* projects need a higher degree of scrutiny963than *peripheral* projects, and the latter may have additional differences.964 965However, this is really only intended to cover common cases966that we have seen arise: different situations are different, and we are open967to discussing unusual cases as well - just start an RFC thread on the968`LLVM Discourse forums`_.969 970Adding a New Target971-------------------972 973LLVM is very receptive to new targets, even experimental ones, but a number of974problems can appear when adding new large portions of code, and back-ends are975normally added in bulk. New targets need the same level of support as other976*core* parts of the compiler, so they are covered in the *core tier* of our977:doc:`support policy<SupportPolicy>`.978 979We have found that landing large pieces of new code and then trying to fix980emergent problems in-tree is problematic for a variety of reasons. For these981reasons, new targets are *always* added as *experimental* until they can be982proven stable, and later moved to non-experimental.983 984The differences between both classes are:985 986* Experimental targets are not built by default (they need to be explicitly987 enabled at CMake time).988 989* Test failures, bugs, and build breakages that only appear when the990 experimental target is enabled, caused by changes unrelated to the target, are991 the responsibility of the community behind the target to fix.992 993The basic rules for a back-end to be upstreamed in **experimental** mode are:994 995* Every target must have at least one :ref:`maintainer<maintainers>`. The996 `Maintainers.rst` file has to be updated as part of the first merge. These997 maintainers make sure that changes to the target get reviewed and steers the998 overall effort.999 1000* There must be an active community behind the target. This community1001 will help maintain the target by providing buildbots, fixing1002 bugs, answering the LLVM community's questions and making sure the new1003 target doesn't break any of the other targets, or generic code. This1004 behavior is expected to continue throughout the lifetime of the1005 target's code.1006 1007* The code must be free of contentious issues, for example, large1008 changes in how the IR behaves or should be formed by the front-ends,1009 unless agreed by the majority of the community via refactoring of the1010 (:doc:`IR standard<LangRef>`) **before** the merge of the new target changes,1011 following the :ref:`IR backwards compatibility`.1012 1013* The code conforms to all of the policies laid out in this developer policy1014 document, including license, patent, and coding standards.1015 1016* The target should have either reasonable documentation on how it1017 works (ISA, ABI, etc.) or a publicly available simulator/hardware1018 (either free or cheap enough) - preferably both. This allows1019 developers to validate assumptions, understand constraints and review code1020 that can affect the target.1021 1022In addition, the rules for a back-end to be promoted to **official** are:1023 1024* The target must have addressed every other minimum requirement and1025 have been stable in tree for at least 3 months. This cool down1026 period is to make sure that the back-end and the target community can1027 endure continuous upstream development for the foreseeable future.1028 1029* The target's code must have been completely adapted to this policy1030 as well as the :doc:`coding standards<CodingStandards>`. Any exceptions that1031 were made to move into experimental mode must have been fixed **before**1032 becoming official.1033 1034* The test coverage needs to be broad and well written (small tests,1035 well documented). The build target ``check-all`` must pass with the1036 new target built, and where applicable, the ``test-suite`` must also1037 pass without errors, in at least one configuration (publicly1038 demonstrated, for example, via buildbots).1039 1040* Public buildbots need to be created and actively maintained, unless1041 the target requires no additional buildbots (ex. ``check-all`` covers1042 all tests). The more relevant and public the new target's CI infrastructure1043 is, the more the LLVM community will embrace it.1044 1045To **continue** as a supported and official target:1046 1047* The maintainer(s) must continue following these rules throughout the lifetime1048 of the target. Continuous violations of aforementioned rules and policies1049 could lead to complete removal of the target from the code base.1050 1051* Degradation in support, documentation or test coverage will make the target as1052 nuisance to other targets and be considered a candidate for deprecation and1053 ultimately removed.1054 1055In essence, these rules are necessary for targets to gain and retain their1056status, but also markers to define bit-rot, and will be used to clean up the1057tree from unmaintained targets.1058 1059Those wishing to add a new target to LLVM must follow the procedure below:1060 10611. Read this section and make sure your target follows all requirements. For1062 minor issues, your community will be responsible for making all necessary1063 adjustments soon after the initial merge.10642. Send a request for comment (RFC) to the `LLVM Discourse forums`_ describing1065 your target and how it follows all the requirements and what work has been1066 done and will need to be done to accommodate the official target requirements.1067 Make sure to expose any and all controversial issues, changes needed in the1068 base code, table gen, etc.10693. Once the response is positive, the LLVM community can start reviewing the1070 actual patches (but they can be prepared before, to support the RFC). Create1071 a sequence of N patches, numbered '1/N' to 'N/N' (make sure N is an actual1072 number, not the letter 'N'), that completes the basic structure of the target.10734. The initial patch should add documentation, maintainers, and triple support in1074 clang and LLVM. The following patches add TableGen infrastructure to describe1075 the target and lower instructions to assembly. The final patch must show that1076 the target can lower correctly with extensive LIT tests (IR to MIR, MIR to1077 ASM, etc).10785. Some patches may be approved before others, but only after *all* patches are1079 approved that the whole set can be merged in one go. This is to guarantee1080 that all changes are good as a single block.10816. After the initial merge, the target community can stop numbering patches and1082 start working asynchronously on the target to complete support. They should1083 still seek review from those who helped them in the initial phase, to make1084 sure the progress is still consistent.10857. Once all official requirements have been fulfilled (as above), the maintainers1086 should request the target to be enabled by default by sending another RFC to1087 the `LLVM Discourse forums`_.1088 1089Adding an Established Project To the LLVM Monorepo1090--------------------------------------------------1091 1092The `LLVM monorepo <https://github.com/llvm/llvm-project>`_ is the centerpoint1093of development in the LLVM world, and has all of the primary LLVM components,1094including the LLVM optimizer and code generators, Clang, LLDB, etc. `Monorepos1095in general <https://en.wikipedia.org/wiki/Monorepo>`_ are great because they1096allow atomic commits to the project, simplify CI, and make it easier for1097subcommunities to collaborate.1098 1099Like new targets, most projects already in the monorepo are considered to be in1100the *core tier* of our :doc:`support policy<SupportPolicy>`. The burden to add1101things to the LLVM monorepo needs to be very high - code that is added to this1102repository is checked out by everyone in the community. As such, we hold1103components to a high bar similar to "official targets", they:1104 1105 * Must be generally aligned with the mission of the LLVM project to advance1106 compilers, languages, tools, runtimes, etc.1107 * Must conform to all of the policies laid out in this developer policy1108 document, including license, patent, coding standards, and code of conduct.1109 * Must have an active community that maintains the code, including established1110 maintainers.1111 * Should have reasonable documentation about how it works, including a high1112 quality README file.1113 * Should have CI to catch breakage within the project itself or due to1114 underlying LLVM dependencies.1115 * Should have code free of issues the community finds contentious, or be on a1116 clear path to resolving them.1117 * Must be proposed through the LLVM RFC process, and have its addition approved1118 by the LLVM community - this ultimately mediates the resolution of the1119 "should" concerns above.1120 1121If you have a project that you think would make sense to add to the LLVM1122monorepo, please start an RFC topic on the `LLVM Discourse forums`_ to kick off1123the discussion. This process can take some time and iteration - please don’t1124be discouraged or intimidated by that!1125 1126If you have an earlier stage project that you think is aligned with LLVM, please1127see the "Incubating New Projects" section.1128 1129Incubating New Projects1130-----------------------1131 1132The burden to add a new project to the LLVM monorepo is intentionally very high,1133but that can have a chilling effect on new and innovative projects. To help1134foster these sorts of projects, LLVM supports an "incubator" process that is1135much easier to get started with. It provides space for potentially valuable,1136new top-level and sub-projects to reach a critical mass before they have enough1137code to prove their utility and grow a community. This also allows1138collaboration between teams that already have permissions to make contributions1139to projects under the LLVM umbrella.1140 1141Projects which can be considered for the LLVM incubator meet the following1142criteria:1143 1144 * Must be generally aligned with the mission of the LLVM project to advance1145 compilers, languages, tools, runtimes, etc.1146 * Must conform to the license, patent, and code of conduct policies laid out1147 in this developer policy document.1148 * Must have a documented charter and development plan, e.g. in the form of a1149 README file, mission statement, and/or manifesto.1150 * Should conform to coding standards, incremental development process, and1151 other expectations.1152 * Should have a sense of the community that it hopes to eventually foster, and1153 there should be interest from members with different affiliations /1154 organizations.1155 * Should have a feasible path to eventually graduate as a dedicated top-level1156 or sub-project within the `LLVM monorepo1157 <https://github.com/llvm/llvm-project>`_.1158 * Should include a notice (e.g. in the project README or web page) that the1159 project is in ‘incubation status’ and is not included in LLVM releases (see1160 suggested wording below).1161 * Must be proposed through the LLVM RFC process, and have its addition1162 approved by the LLVM community - this ultimately mediates the resolution of1163 the "should" concerns above.1164 1165That said, the project need not have any code to get started, and need not have1166an established community at all! Furthermore, incubating projects may pass1167through transient states that violate the "Should" guidelines above, or would1168otherwise make them unsuitable for direct inclusion in the monorepo (e.g.1169dependencies that have not yet been factored appropriately, leveraging1170experimental components or APIs that are not yet upstream, etc).1171 1172When approved, the llvm-admin group can grant the new project:1173 * A new repository in the LLVM Github Organization - but not the LLVM monorepo.1174 * New mailing list, discourse forum, and/or discord chat hosted with other LLVM1175 forums.1176 * Other infrastructure integration can be discussed on a case-by-case basis.1177 1178Graduation to the mono-repo would follow existing processes and standards for1179becoming a first-class part of the monorepo. Similarly, an incubating project1180may be eventually retired, but no process has been established for that yet. If1181and when this comes up, please start an RFC discussion on the `LLVM Discourse forums`_.1182 1183This process is very new - please expect the details to change, it is always1184safe to ask on the `LLVM Discourse forums`_ about this.1185 1186Suggested disclaimer for the project README and the main project web page:1187 1188::1189 1190 This project is participating in the LLVM Incubator process: as such, it is1191 not part of any official LLVM release. While incubation status is not1192 necessarily a reflection of the completeness or stability of the code, it1193 does indicate that the project is not yet endorsed as a component of LLVM.1194 1195Adding or enabling a new LLVM pass1196----------------------------------1197 1198The guidelines here are primarily targeted at the enablement of new major1199passes in the target-independent optimization pipeline. Small additions, or1200backend-specific passes, require a lesser degree of care. Before creating a new1201pass, consider whether the functionality can be integrated into an existing1202pass first. This is often both faster and more powerful.1203 1204When adding a new pass, the goal should be to enable it as part of the default1205optimization pipeline as early as possible and then continue development1206incrementally. (This does not apply to passes that are only relevant for1207specific uses of LLVM, such as GC support passes.)1208 1209The recommended workflow is:1210 12111. Implement a basic version of the pass and add it to the pass pipeline behind1212 a flag that is disabled by default. The initial version should focus on1213 handling simple cases correctly and efficiently.12142. Enable the pass by default. Separating this step allows easily disabling the1215 pass if issues are encountered, without having to revert the entire1216 implementation.12173. Incrementally extend the pass with new functionality. As the pass is already1218 enabled, it becomes easier to identify the specific change that has caused a1219 regression in correctness, optimization quality or compile-time.1220 1221When enabling a pass, certain requirements must be met (in no particular order):1222 1223 * **Maintenance:** The pass (and any analyses it depends on) must have at1224 least one maintainer.1225 * **Usefulness:** There should be evidence that the pass improves performance1226 (or whatever metric it optimizes for) on real-world workloads. Improvements1227 seen only on synthetic benchmarks may be insufficient.1228 * **Compile-Time:** The pass should not have a large impact on compile-time,1229 where the evaluation of what "large" means is up to reviewer discretion, and1230 may differ based on the value the pass provides. In any case, it is expected1231 that a concerted effort has been made to mitigate the compile-time impact,1232 both for the average case, and for pathological cases.1233 * **Correctness:** The pass should have no known correctness issues (except1234 global correctness issues that affect all of LLVM). If an old pass is being1235 enabled (rather than implementing a new one incrementally), additional due1236 diligence is required. The pass should be fully reviewed to ensure that it1237 still complies with current quality standards. Fuzzing with disabled1238 profitability checks may help gain additional confidence in the1239 implementation.1240 1241If non-trivial issues are found in a newly enabled pass, it may be temporarily1242disabled again, until the issues have been resolved.1243 1244.. _copyright-license-patents:1245 1246Copyright, License, and Patents1247===============================1248 1249.. note::1250 1251 This section deals with legal matters but does not provide legal advice. We1252 are not lawyers --- please seek legal counsel from a licensed attorney.1253 1254This section addresses the issues of copyright, license and patents for the LLVM1255project. The copyright for the code is held by the contributors of1256the code. The code is licensed under permissive `open source licensing terms`_,1257namely the Apache-2.0 with LLVM-exception license, which includes a copyright1258and `patent license`_. When you contribute code to the LLVM project, you1259license it under these terms.1260 1261In certain circumstances, code licensed under other licenses can be added1262to the codebase. However, this may only be done with approval of the LLVM1263Foundation Board of Directors, and contributors should plan for the approval1264process to take at least 4-6 weeks. If you would like to contribute code1265under a different license, please create a pull request with the code1266you want to contribute and email board@llvm.org requesting a review.1267 1268If you have questions or comments about these topics, please ask on the1269`LLVM Discourse forums`_. However,1270please realize that most compiler developers are not lawyers, and therefore you1271will not be getting official legal advice.1272 1273.. _LLVM Discourse forums: https://discourse.llvm.org1274 1275Copyright1276---------1277 1278The LLVM project does not collect copyright assignments, which means that the1279copyright for the code in the project is held by the respective contributors.1280Because you (or your company)1281retain ownership of the code you contribute, you know it may only be used under1282the terms of the open source license you contributed it under: the license for1283your contributions cannot be changed in the future without your approval.1284 1285Because the LLVM project does not require copyright assignments, changing the1286LLVM license requires tracking down the1287contributors to LLVM and getting them to agree that a license change is1288acceptable for their contributions. We feel that a high burden for relicensing1289is good for the project, because contributors do not have to fear that their1290code will be used in a way with which they disagree.1291 1292Embedded Copyright or 'Contributed by' Statements1293^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^1294 1295The LLVM project does not accept contributions that include in-source copyright1296notices except where such notices are part of a larger external project being1297added as a vendored dependency.1298 1299LLVM source code lives for a long time and is edited by many people, the best1300way to track contributions is through revision control history.1301See the `Attribution of Changes`_ section for more information about attributing1302changes to authors other than the committer.1303 1304Relicensing1305-----------1306 1307The last paragraph notwithstanding, the LLVM Project is in the middle of a large1308effort to change licenses, which aims to solve several problems:1309 1310* The old licenses made it difficult to move code from (e.g.) the compiler to1311 runtime libraries, because runtime libraries used a different license from the1312 rest of the compiler.1313* Some contributions were not submitted to LLVM due to concerns that1314 the patent grant required by the project was overly broad.1315* The patent grant was unique to the LLVM Project, not written by a lawyer, and1316 was difficult to determine what protection was provided (if any).1317 1318The scope of relicensing is all code that is considered part of the LLVM1319project, including the main LLVM repository, runtime libraries (compiler_rt,1320OpenMP, etc), Polly, and all other subprojects. There are a few exceptions:1321 1322* Code imported from other projects (e.g. Google Test, Autoconf, etc) will1323 remain as it is. This code isn't developed as part of the LLVM project, it1324 is used by LLVM.1325* Some subprojects are impractical or uninteresting to relicense (e.g. llvm-gcc1326 and dragonegg). These will be split off from the LLVM project (e.g. to1327 separate GitHub projects), allowing interested people to continue their1328 development elsewhere.1329 1330To relicense LLVM, we will be seeking approval from all of the copyright holders1331of code in the repository, or potentially remove/rewrite code if we cannot.1332This is a large1333and challenging project which will take a significant amount of time to1334complete.1335 1336Starting on 2024-06-01 (first of June 2024), new contributions only need to1337be covered by the new LLVM license, i.e. Apache-2.0 WITH LLVM-exception.1338Before this date, the project required all contributions to be made under1339both the new license and the legacy license.1340 1341If you are a contributor to LLVM with contributions committed before 2019-01-191342and have not done so already, please do follow the instructions at1343https://foundation.llvm.org/docs/relicensing/, under section "Individual1344Relicensing Agreement" to relicense your contributions under the new license.1345 1346 1347.. _open source licensing terms:1348 1349New LLVM Project License Framework1350----------------------------------1351 1352Contributions to LLVM are licensed under the `Apache License, Version 2.01353<https://www.apache.org/licenses/LICENSE-2.0>`_, with two limited1354exceptions intended to ensure that LLVM is very permissively licensed.1355Collectively, the name of this license is "Apache 2.0 License with LLVM1356exceptions". The exceptions read:1357 1358::1359 1360 ---- LLVM Exceptions to the Apache 2.0 License ----1361 1362 As an exception, if, as a result of your compiling your source code, portions1363 of this Software are embedded into an Object form of such source code, you1364 may redistribute such embedded portions in such Object form without complying1365 with the conditions of Sections 4(a), 4(b) and 4(d) of the License.1366 1367 In addition, if you combine or link compiled forms of this Software with1368 software that is licensed under the GPLv2 ("Combined Software") and if a1369 court of competent jurisdiction determines that the patent provision (Section1370 3), the indemnity provision (Section 9) or other Section of the License1371 conflicts with the conditions of the GPLv2, you may retroactively and1372 prospectively choose to deem waived or otherwise exclude such Section(s) of1373 the License, but only in their entirety and only with respect to the Combined1374 Software.1375 1376 1377We intend to keep LLVM perpetually open source and available under a permissive1378license - this fosters the widest adoption of LLVM by1379**allowing commercial products to be derived from LLVM** with few restrictions1380and without a requirement for making any derived works also open source. In1381particular, LLVM's license is not a "copyleft" license like the GPL.1382 1383The "Apache 2.0 License with LLVM exceptions" allows you to:1384 1385* freely download and use LLVM (in whole or in part) for personal, internal, or1386 commercial purposes.1387* include LLVM in packages or distributions you create.1388* combine LLVM with code licensed under every other major open source1389 license (including BSD, MIT, GPLv2, GPLv3...).1390* make changes to LLVM code without being required to contribute it back1391 to the project - contributions are appreciated though!1392 1393However, it imposes these limitations on you:1394 1395* You must retain the copyright notice if you redistribute LLVM: You cannot1396 strip the copyright headers off or replace them with your own.1397* Binaries that include LLVM must reproduce the copyright notice (e.g. in an1398 included README file or in an "About" box), unless the LLVM code was added as1399 a by-product of compilation. For example, if an LLVM runtime library like1400 compiler_rt or libc++ was automatically included into your application by the1401 compiler, you do not need to attribute it.1402* You can't use our names to promote your products (LLVM derived or not) -1403 though you can make truthful statements about your use of the LLVM code,1404 without implying our sponsorship.1405* There's no warranty on LLVM at all.1406 1407We want LLVM code to be widely used, and believe that this provides a model that1408is great for contributors and users of the project. For more information about1409the Apache 2.0 License, please see the `Apache License FAQ1410<http://www.apache.org/foundation/license-faq.html>`_, maintained by the1411Apache Project.1412 1413.. _patent license:1414 1415Patents1416-------1417 1418Section 3 of the Apache 2.0 license is a patent grant under which1419contributors of code to the project contribute the rights to use any of1420their patents that would otherwise be infringed by that code contribution1421(protecting uses of that code). Further, the patent grant is revoked1422from anyone who files a patent lawsuit about code in LLVM - this protects the1423community by providing a "patent commons" for the code base and reducing the1424odds of patent lawsuits in general.1425 1426The license specifically scopes which patents are included with code1427contributions. To help explain this, the `Apache License FAQ1428<http://www.apache.org/foundation/license-faq.html>`_ explains this scope using1429some questions and answers, which we reproduce here for your convenience (for1430reference, the "ASF" is the Apache Software Foundation, the guidance still1431holds though)::1432 1433 Q1: If I own a patent and contribute to a Work, and, at the time my1434 contribution is included in that Work, none of my patent's claims are subject1435 to Apache's Grant of Patent License, is there a way any of those claims would1436 later become subject to the Grant of Patent License solely due to subsequent1437 contributions by other parties who are not licensees of that patent.1438 1439 A1: No.1440 1441 Q2: If at any time after my contribution, I am able to license other patent1442 claims that would have been subject to Apache's Grant of Patent License if1443 they were licensable by me at the time of my contribution, do those other1444 claims become subject to the Grant of Patent License?1445 1446 A2: Yes.1447 1448 Q3: If I own or control a licensable patent and contribute code to a specific1449 Apache product, which of my patent claims are subject to Apache's Grant of1450 Patent License?1451 1452 A3: The only patent claims that are licensed to the ASF are those you own or1453 have the right to license that read on your contribution or on the1454 combination of your contribution with the specific Apache product to which1455 you contributed as it existed at the time of your contribution. No additional1456 patent claims become licensed as a result of subsequent combinations of your1457 contribution with any other software. Note, however, that licensable patent1458 claims include those that you acquire in the future, as long as they read on1459 your original contribution as made at the original time. Once a patent claim1460 is subject to Apache's Grant of Patent License, it is licensed under the1461 terms of that Grant to the ASF and to recipients of any software distributed1462 by the ASF for any Apache software product whatsoever.1463 1464.. _legacy:1465 1466Legacy License Structure1467------------------------1468 1469.. note::1470 The code base was previously licensed under the Terms described here.1471 We are in the middle of relicensing to a new approach (described above).1472 More than 99% of all contributions made to LLVM are covered by the Apache-2.01473 WITH LLVM-exception license. A small portion of LLVM code remains exclusively1474 covered by the legacy license. Contributions after 2024-06-01 are covered1475 exclusively by the new license._1476 1477We intend to keep LLVM perpetually open source and to use a permissive open1478source license. The code in1479LLVM is available under the `University of Illinois/NCSA Open Source License1480<http://www.opensource.org/licenses/UoI-NCSA.php>`_, which boils down to1481this:1482 1483* You can freely distribute LLVM.1484* You must retain the copyright notice if you redistribute LLVM.1485* Binaries derived from LLVM must reproduce the copyright notice (e.g. in an1486 included README file).1487* You can't use our names to promote your LLVM derived products.1488* There's no warranty on LLVM at all.1489 1490We believe this fosters the widest adoption of LLVM because it **allows1491commercial products to be derived from LLVM** with few restrictions and without1492a requirement for making any derived works also open source (i.e. LLVM's1493license is not a "copyleft" license like the GPL). We suggest that you read the1494`License <http://www.opensource.org/licenses/UoI-NCSA.php>`_ if further1495clarification is needed.1496 1497In addition to the UIUC license, the runtime library components of LLVM1498(**compiler_rt, libc++, and libclc**) are also licensed under the `MIT License1499<http://www.opensource.org/licenses/mit-license.php>`_, which does not contain1500the binary redistribution clause. As a user of these runtime libraries, it1501means that you can choose to use the code under either license (and thus don't1502need the binary redistribution clause), and as a contributor to the code that1503you agree that any contributions to these libraries be licensed under both1504licenses. We feel that this is important for runtime libraries, because they1505are implicitly linked into applications and therefore should not subject those1506applications to the binary redistribution clause. This also means that it is ok1507to move code from (e.g.) libc++ to the LLVM core without concern, but that code1508cannot be moved from the LLVM core to libc++ without the copyright owner's1509permission.1510 1511.. _ai contributions:1512 1513AI generated contributions1514--------------------------1515 1516Artificial intelligence systems raise many questions around copyright that have1517yet to be answered. Our policy on AI tools is guided by our copyright policy:1518Contributors are responsible for ensuring that they have the right to contribute1519code under the terms of our license, typically meaning that either they, their1520employer, or their collaborators hold the copyright. Using AI tools to1521regenerate copyrighted material does not remove the copyright, and contributors1522are responsible for ensuring that such material does not appear in their1523contributions.1524 1525As such, the LLVM policy is that contributors are permitted to use artificial1526intelligence tools to produce contributions, provided that they have the right1527to license that code under the project license. Contributions found to violate1528this policy will be removed just like any other offending contribution.1529 1530While the LLVM project has a liberal policy on AI tool use, contributors are1531considered responsible for their contributions. We encourage contributors to1532review all generated code before sending it for review to verify its1533correctness and to understand it so that they can answer questions during code1534review. Reviewing and maintaining generated code that the original contributor1535does not understand is not a good use of limited project resources.1536