1===================== 2LLVM Developer Policy 3===================== 4 5.. contents:: 6 :local: 7 8Introduction 9============ 10 11This document contains the LLVM Developer Policy which defines the project's 12policy towards developers and their contributions. The intent of this policy is 13to eliminate miscommunication, rework, and confusion that might arise from the 14distributed nature of LLVM's development. By stating the policy in clear terms, 15we hope each developer can know ahead of time what to expect when making LLVM 16contributions. This policy covers all llvm.org subprojects, including Clang, 17LLDB, libc++, etc. 18 19This policy is also designed to accomplish the following objectives: 20 21#. Attract both users and developers to the LLVM project. 22 23#. Make life as simple and easy for contributors as possible. 24 25#. Keep the top of tree as stable as possible. 26 27#. Establish awareness of the project's :ref:`copyright, license, and patent 28 policies <copyright-license-patents>` with contributors to the project. 29 30This policy is aimed at frequent contributors to LLVM. People interested in 31contributing one-off patches can do so in an informal way by sending them to the 32`llvm-commits mailing list 33<http://lists.llvm.org/mailman/listinfo/llvm-commits>`_ and engaging another 34developer to see it through the process. 35 36Developer Policies 37================== 38 39This section contains policies that pertain to frequent LLVM developers. We 40always welcome `one-off patches`_ from people who do not routinely contribute to 41LLVM, but we expect more from frequent contributors to keep the system as 42efficient as possible for everyone. Frequent LLVM contributors are expected to 43meet the following requirements in order for LLVM to maintain a high standard of 44quality. 45 46Stay Informed 47------------- 48 49Developers should stay informed by reading at least the "dev" mailing list for 50the projects you are interested in, such as `llvm-dev 51<http://lists.llvm.org/mailman/listinfo/llvm-dev>`_ for LLVM, `cfe-dev 52<http://lists.llvm.org/mailman/listinfo/cfe-dev>`_ for Clang, or `lldb-dev 53<http://lists.llvm.org/mailman/listinfo/lldb-dev>`_ for LLDB. If you are 54doing anything more than just casual work on LLVM, it is suggested that you also 55subscribe to the "commits" mailing list for the subproject you're interested in, 56such as `llvm-commits 57<http://lists.llvm.org/mailman/listinfo/llvm-commits>`_, `cfe-commits 58<http://lists.llvm.org/mailman/listinfo/cfe-commits>`_, or `lldb-commits 59<http://lists.llvm.org/mailman/listinfo/lldb-commits>`_. Reading the 60"commits" list and paying attention to changes being made by others is a good 61way to see what other people are interested in and watching the flow of the 62project as a whole. 63 64We recommend that active developers register an email account with `LLVM 65Bugzilla <https://bugs.llvm.org/>`_ and preferably subscribe to the `llvm-bugs 66<http://lists.llvm.org/mailman/listinfo/llvm-bugs>`_ email list to keep track 67of bugs and enhancements occurring in LLVM. We really appreciate people who are 68proactive at catching incoming bugs in their components and dealing with them 69promptly. 70 71Please be aware that all public LLVM mailing lists are public and archived, and 72that notices of confidentiality or non-disclosure cannot be respected. 73 74.. _patch: 75.. _one-off patches: 76 77Making and Submitting a Patch 78----------------------------- 79 80When making a patch for review, the goal is to make it as easy for the reviewer 81to read it as possible. As such, we recommend that you: 82 83#. Make your patch against git main, not a branch, and not an old version 84 of LLVM. This makes it easy to apply the patch. For information on how to 85 clone from git, please see the :ref:`Getting Started Guide 86 <checkout>`. 87 88#. Similarly, patches should be submitted soon after they are generated. Old 89 patches may not apply correctly if the underlying code changes between the 90 time the patch was created and the time it is applied. 91 92#. Patches should be made with ``git format-patch``, or similar (see special 93 commands for `Requesting Phabricator review via the web interface 94 <Phabricator.html#phabricator-request-review-web>`_ ). If you use a 95 different tool, make sure it uses the ``diff -u`` format and that it 96 doesn't contain clutter which makes it hard to read. 97 98Once your patch is ready, submit it by emailing it to the appropriate project's 99commit mailing list (or commit it directly if applicable). Alternatively, some 100patches get sent to the project's development list or component of the LLVM bug 101tracker, but the commit list is the primary place for reviews and should 102generally be preferred. 103 104When sending a patch to a mailing list, it is a good idea to send it as an 105*attachment* to the message, not embedded into the text of the message. This 106ensures that your mailer will not mangle the patch when it sends it (e.g. by 107making whitespace changes or by wrapping lines). 108 109*For Thunderbird users:* Before submitting a patch, please open *Preferences > 110Advanced > General > Config Editor*, find the key 111``mail.content_disposition_type``, and set its value to ``1``. Without this 112setting, Thunderbird sends your attachment using ``Content-Disposition: inline`` 113rather than ``Content-Disposition: attachment``. Apple Mail gamely displays such 114a file inline, making it difficult to work with for reviewers using that 115program. 116 117When submitting patches, please do not add confidentiality or non-disclosure 118notices to the patches themselves. These notices conflict with the LLVM 119licensing terms and may result in your contribution being excluded. 120 121.. _code review: 122 123Code Reviews 124------------ 125 126LLVM has a code-review policy. Code review is one way to increase the quality of 127software. Please see :doc:`CodeReview` for more information on LLVM's code-review 128process. 129 130.. _code owners: 131 132Code Owners 133----------- 134 135The LLVM Project relies on two features of its process to maintain rapid 136development in addition to the high quality of its source base: the combination 137of code review plus post-commit review for trusted maintainers. Having both is 138a great way for the project to take advantage of the fact that most people do 139the right thing most of the time, and only commit patches without pre-commit 140review when they are confident they are right. 141 142The trick to this is that the project has to guarantee that all patches that are 143committed are reviewed after they go in: you don't want everyone to assume 144someone else will review it, allowing the patch to go unreviewed. To solve this 145problem, we have a notion of an 'owner' for a piece of the code. The sole 146responsibility of a code owner is to ensure that a commit to their area of the 147code is appropriately reviewed, either by themself or by someone else. The list 148of current code owners can be found in the file `CODE_OWNERS.TXT 149<https://github.com/llvm/llvm-project/blob/main/llvm/CODE_OWNERS.TXT>`_ in the 150root of the LLVM source tree. 151 152Note that code ownership is completely different than reviewers: anyone can 153review a piece of code, and we welcome code review from anyone who is 154interested. Code owners are the "last line of defense" to guarantee that all 155patches that are committed are actually reviewed. 156 157Being a code owner is a somewhat unglamorous position, but it is incredibly 158important for the ongoing success of the project. Because people get busy, 159interests change, and unexpected things happen, code ownership is purely opt-in, 160and anyone can choose to resign their "title" at any time. For now, we do not 161have an official policy on how one gets elected to be a code owner. 162 163.. _include a testcase: 164 165Test Cases 166---------- 167 168Developers are required to create test cases for any bugs fixed and any new 169features added. Some tips for getting your testcase approved: 170 171* All feature and regression test cases are added to the ``llvm/test`` 172 directory. The appropriate sub-directory should be selected (see the 173 :doc:`Testing Guide <TestingGuide>` for details). 174 175* Test cases should be written in :doc:`LLVM assembly language <LangRef>`. 176 177* Test cases, especially for regressions, should be reduced as much as possible, 178 by :doc:`bugpoint <Bugpoint>` or manually. It is unacceptable to place an 179 entire failing program into ``llvm/test`` as this creates a *time-to-test* 180 burden on all developers. Please keep them short. 181 182Note that llvm/test and clang/test are designed for regression and small feature 183tests only. More extensive test cases (e.g., entire applications, benchmarks, 184etc) should be added to the ``llvm-test`` test suite. The llvm-test suite is 185for coverage (correctness, performance, etc) testing, not feature or regression 186testing. 187 188Quality 189------- 190 191The minimum quality standards that any change must satisfy before being 192committed to the main development branch are: 193 194#. Code must adhere to the `LLVM Coding Standards <CodingStandards.html>`_. 195 196#. Code must compile cleanly (no errors, no warnings) on at least one platform. 197 198#. Bug fixes and new features should `include a testcase`_ so we know if the 199 fix/feature ever regresses in the future. 200 201#. Code must pass the ``llvm/test`` test suite. 202 203#. The code must not cause regressions on a reasonable subset of llvm-test, 204 where "reasonable" depends on the contributor's judgement and the scope of 205 the change (more invasive changes require more testing). A reasonable subset 206 might be something like "``llvm-test/MultiSource/Benchmarks``". 207 208Additionally, the committer is responsible for addressing any problems found in 209the future that the change is responsible for. For example: 210 211* The code should compile cleanly on all supported platforms. 212 213* The changes should not cause any correctness regressions in the ``llvm-test`` 214 suite and must not cause any major performance regressions. 215 216* The change set should not cause performance or correctness regressions for the 217 LLVM tools. 218 219* The changes should not cause performance or correctness regressions in code 220 compiled by LLVM on all applicable targets. 221 222* You are expected to address any `Bugzilla bugs <https://bugs.llvm.org/>`_ that 223 result from your change. 224 225We prefer for this to be handled before submission but understand that it isn't 226possible to test all of this for every submission. Our build bots and nightly 227testing infrastructure normally finds these problems. A good rule of thumb is 228to check the nightly testers for regressions the day after your change. Build 229bots will directly email you if a group of commits that included yours caused a 230failure. You are expected to check the build bot messages to see if they are 231your fault and, if so, fix the breakage. 232 233Commits that violate these quality standards (e.g. are very broken) may be 234reverted. This is necessary when the change blocks other developers from making 235progress. The developer is welcome to re-commit the change after the problem has 236been fixed. 237 238.. _commit messages: 239 240Commit messages 241--------------- 242 243Although we don't enforce the format of commit messages, we prefer that 244you follow these guidelines to help review, search in logs, email formatting 245and so on. These guidelines are very similar to rules used by other open source 246projects. 247 248Most importantly, the contents of the message should be carefully written to 249convey the rationale of the change (without delving too much in detail). It 250also should avoid being vague or overly specific. For example, "bits were not 251set right" will leave the reviewer wondering about which bits, and why they 252weren't right, while "Correctly set overflow bits in TargetInfo" conveys almost 253all there is to the change. 254 255Below are some guidelines about the format of the message itself: 256 257* Separate the commit message into title and body separated by a blank line. 258 259* If you're not the original author, ensure the 'Author' property of the commit is 260 set to the original author and the 'Committer' property is set to yourself. 261 You can use a command similar to 262 ``git commit --amend --author="John Doe <jdoe@llvm.org>"`` to correct the 263 author property if it is incorrect. See `Attribution of Changes`_ for more 264 information including the method we used for attribution before the project 265 migrated to git. 266 267* The title should be concise. Because all commits are emailed to the list with 268 the first line as the subject, long titles are frowned upon. Short titles 269 also look better in `git log`. 270 271* When the changes are restricted to a specific part of the code (e.g. a 272 back-end or optimization pass), it is customary to add a tag to the 273 beginning of the line in square brackets. For example, "[SCEV] ..." 274 or "[OpenMP] ...". This helps email filters and searches for post-commit 275 reviews. 276 277* The body, if it exists, should be separated from the title by an empty line. 278 279* The body should be concise, but explanatory, including a complete 280 reasoning. Unless it is required to understand the change, examples, 281 code snippets and gory details should be left to bug comments, web 282 review or the mailing list. 283 284* If the patch fixes a bug in bugzilla, please include the PR# in the message. 285 286* Text formatting and spelling should follow the same rules as documentation 287 and in-code comments, ex. capitalization, full stop, etc. 288 289* If the commit is a bug fix on top of another recently committed patch, or a 290 revert or reapply of a patch, include the git commit hash of the prior 291 related commit. This could be as simple as "Revert commit NNNN because it 292 caused PR#". 293 294* If the patch has been reviewed, add a link to its review page, as shown 295 `here <https://www.llvm.org/docs/Phabricator.html#committing-a-change>`_. 296 297For minor violations of these recommendations, the community normally favors 298reminding the contributor of this policy over reverting. Minor corrections and 299omissions can be handled by sending a reply to the commits mailing list. 300 301.. _revert_policy: 302 303Patch reversion policy 304---------------------- 305 306As a community, we strongly value having the tip of tree in a good state while 307allowing rapid iterative development. As such, we tend to make much heavier 308use of reverts to keep the tree healthy than some other open source projects, 309and our norms are a bit different. 310 311How should you respond if someone reverted your change? 312 313* Remember, it is normal and healthy to have patches reverted. Having a patch 314 reverted does not necessarily mean you did anything wrong. 315* We encourage explicitly thanking the person who reverted the patch for doing 316 the task on your behalf. 317* If you need more information to address the problem, please follow up in the 318 original commit thread with the reverting patch author. 319 320When should you revert your own change? 321 322* Any time you learn of a serious problem with a change, you should revert it. 323 We strongly encourage "revert to green" as opposed to "fixing forward". We 324 encourage reverting first, investigating offline, and then reapplying the 325 fixed patch - possibly after another round of review if warranted. 326* If you break a buildbot in a way which can't be quickly fixed, please revert. 327* If a test case that demonstrates a problem is reported in the commit thread, 328 please revert and investigate offline. 329* If you receive substantial :ref:`post-commit review <post_commit_review>` 330 feedback, please revert and address said feedback before recommitting. 331 (Possibly after another round of review.) 332* If you are asked to revert by another contributor, please revert and discuss 333 the merits of the request offline (unless doing so would further destabilize 334 tip of tree). 335 336When should you revert someone else's change? 337 338* In general, if the author themselves would revert the change per these 339 guidelines, we encourage other contributors to do so as a courtesy to the 340 author. This is one of the major cases where our norms differ from others; 341 we generally consider reverting a normal part of development. We don't 342 expect contributors to be always available, and the assurance that a 343 problematic patch will be reverted and we can return to it at our next 344 opportunity enables this. 345 346What are the expectations around a revert? 347 348* Use your best judgment. If you're uncertain, please start an email on 349 the commit thread asking for assistance. We aren't trying to enumerate 350 every case, but rather give a set of guidelines. 351* You should be sure that reverting the change improves the stability of tip 352 of tree. Sometimes reverting one change in a series can worsen things 353 instead of improving them. We expect reasonable judgment to ensure that 354 the proper patch or set of patches is being reverted. 355* The commit message for the reverting commit should explain why patch 356 is being reverted. 357* It is customary to respond to the original commit email mentioning the 358 revert. This serves as both a notice to the original author that their 359 patch was reverted, and helps others following llvm-commits track context. 360* Ideally, you should have a publicly reproducible test case ready to share. 361 Where possible, we encourage sharing of test cases in commit threads, or 362 in PRs. We encourage the reverter to minimize the test case and to prune 363 dependencies where practical. This even applies when reverting your own 364 patch; documenting the reasons for others who might be following along 365 is critical. 366* It is not considered reasonable to revert without at least the promise to 367 provide a means for the patch author to debug the root issue. If a situation 368 arises where a public reproducer can not be shared for some reason (e.g. 369 requires hardware patch author doesn't have access to, sharp regression in 370 compile time of internal workload, etc.), the reverter is expected to be 371 proactive about working with the patch author to debug and test candidate 372 patches. 373* Reverts should be reasonably timely. A change submitted two hours ago 374 can be reverted without prior discussion. A change submitted two years ago 375 should not be. Where exactly the transition point is is hard to say, but 376 it's probably in the handful of days in tree territory. If you are unsure, 377 we encourage you to reply to the commit thread, give the author a bit to 378 respond, and then proceed with the revert if the author doesn't seem to be 379 actively responding. 380* When re-applying a reverted patch, the commit message should be updated to 381 indicate the problem that was addressed and how it was addressed. 382 383Obtaining Commit Access 384----------------------- 385 386We grant commit access to contributors with a track record of submitting high 387quality patches. If you would like commit access, please send an email to 388`Chris <mailto:clattner@llvm.org>`_ with your GitHub username. This is true 389for former contributors with SVN access as well as new contributors. 390 391Prior to obtaining commit access, it is common practice to request that 392someone with commit access commits on your behalf. When doing so, please 393provide the name and email address you would like to use in the Author 394property of the commit. 395 396Your first commit to a repository may require the autogenerated email to be 397approved by a moderator of the mailing list. 398This is normal and will be done when the mailing list owner has time. 399 400If you have recently been granted commit access, these policies apply: 401 402#. You are granted *commit-after-approval* to all parts of LLVM. For 403 information on how to get approval for a patch, please see :doc:`CodeReview`. 404 When approved, you may commit it yourself. 405 406#. You are allowed to commit patches without approval which you think are 407 obvious. This is clearly a subjective decision --- we simply expect you to 408 use good judgement. Examples include: fixing build breakage, reverting 409 obviously broken patches, documentation/comment changes, any other minor 410 changes. Avoid committing formatting- or whitespace-only changes outside of 411 code you plan to make subsequent changes to. Also, try to separate 412 formatting or whitespace changes from functional changes, either by 413 correcting the format first (ideally) or afterward. Such changes should be 414 highly localized and the commit message should clearly state that the commit 415 is not intended to change functionality, usually by stating it is 416 :ref:`NFC <nfc>`. 417 418#. You are allowed to commit patches without approval to those portions of LLVM 419 that you have contributed or maintain (i.e., have been assigned 420 responsibility for), with the proviso that such commits must not break the 421 build. This is a "trust but verify" policy, and commits of this nature are 422 reviewed after they are committed. 423 424#. Multiple violations of these policies or a single egregious violation may 425 cause commit access to be revoked. 426 427In any case, your changes are still subject to `code review`_ (either before or 428after they are committed, depending on the nature of the change). You are 429encouraged to review other peoples' patches as well, but you aren't required 430to do so. 431 432.. _discuss the change/gather consensus: 433 434Making a Major Change 435--------------------- 436 437When a developer begins a major new project with the aim of contributing it back 438to LLVM, they should inform the community with an email to the `llvm-dev 439<http://lists.llvm.org/mailman/listinfo/llvm-dev>`_ email list, to the extent 440possible. The reason for this is to: 441 442#. keep the community informed about future changes to LLVM, 443 444#. avoid duplication of effort by preventing multiple parties working on the 445 same thing and not knowing about it, and 446 447#. ensure that any technical issues around the proposed work are discussed and 448 resolved before any significant work is done. 449 450The design of LLVM is carefully controlled to ensure that all the pieces fit 451together well and are as consistent as possible. If you plan to make a major 452change to the way LLVM works or want to add a major new extension, it is a good 453idea to get consensus with the development community before you start working on 454it. 455 456Once the design of the new feature is finalized, the work itself should be done 457as a series of `incremental changes`_, not as a long-term development branch. 458 459.. _incremental changes: 460 461Incremental Development 462----------------------- 463 464In the LLVM project, we do all significant changes as a series of incremental 465patches. We have a strong dislike for huge changes or long-term development 466branches. Long-term development branches have a number of drawbacks: 467 468#. Branches must have mainline merged into them periodically. If the branch 469 development and mainline development occur in the same pieces of code, 470 resolving merge conflicts can take a lot of time. 471 472#. Other people in the community tend to ignore work on branches. 473 474#. Huge changes (produced when a branch is merged back onto mainline) are 475 extremely difficult to `code review`_. 476 477#. Branches are not routinely tested by our nightly tester infrastructure. 478 479#. Changes developed as monolithic large changes often don't work until the 480 entire set of changes is done. Breaking it down into a set of smaller 481 changes increases the odds that any of the work will be committed to the main 482 repository. 483 484To address these problems, LLVM uses an incremental development style and we 485require contributors to follow this practice when making a large/invasive 486change. Some tips: 487 488* Large/invasive changes usually have a number of secondary changes that are 489 required before the big change can be made (e.g. API cleanup, etc). These 490 sorts of changes can often be done before the major change is done, 491 independently of that work. 492 493* The remaining inter-related work should be decomposed into unrelated sets of 494 changes if possible. Once this is done, define the first increment and get 495 consensus on what the end goal of the change is. 496 497* Each change in the set can be stand alone (e.g. to fix a bug), or part of a 498 planned series of changes that works towards the development goal. 499 500* Each change should be kept as small as possible. This simplifies your work 501 (into a logical progression), simplifies code review and reduces the chance 502 that you will get negative feedback on the change. Small increments also 503 facilitate the maintenance of a high quality code base. 504 505* Often, an independent precursor to a big change is to add a new API and slowly 506 migrate clients to use the new API. Each change to use the new API is often 507 "obvious" and can be committed without review. Once the new API is in place 508 and used, it is much easier to replace the underlying implementation of the 509 API. This implementation change is logically separate from the API 510 change. 511 512If you are interested in making a large change, and this scares you, please make 513sure to first `discuss the change/gather consensus`_ then ask about the best way 514to go about making the change. 515 516Attribution of Changes 517---------------------- 518 519When contributors submit a patch to an LLVM project, other developers with 520commit access may commit it for the author once appropriate (based on the 521progression of code review, etc.). When doing so, it is important to retain 522correct attribution of contributions to their contributors. However, we do not 523want the source code to be littered with random attributions "this code written 524by J. Random Hacker" (this is noisy and distracting). In practice, the revision 525control system keeps a perfect history of who changed what, and the CREDITS.txt 526file describes higher-level contributions. If you commit a patch for someone 527else, please follow the attribution of changes in the simple manner as outlined 528by the `commit messages`_ section. Overall, please do not add contributor names 529to the source code. 530 531Also, don't commit patches authored by others unless they have submitted the 532patch to the project or you have been authorized to submit them on their behalf 533(you work together and your company authorized you to contribute the patches, 534etc.). The author should first submit them to the relevant project's commit 535list, development list, or LLVM bug tracker component. If someone sends you 536a patch privately, encourage them to submit it to the appropriate list first. 537 538Our previous version control system (subversion) did not distinguish between the 539author and the committer like git does. As such, older commits used a different 540attribution mechanism. The previous method was to include "Patch by John Doe." 541in a separate line of the commit message and there are automated processes that 542rely on this format. 543 544.. _IR backwards compatibility: 545 546IR Backwards Compatibility 547-------------------------- 548 549When the IR format has to be changed, keep in mind that we try to maintain some 550backwards compatibility. The rules are intended as a balance between convenience 551for llvm users and not imposing a big burden on llvm developers: 552 553* The textual format is not backwards compatible. We don't change it too often, 554 but there are no specific promises. 555 556* Additions and changes to the IR should be reflected in 557 ``test/Bitcode/compatibility.ll``. 558 559* The current LLVM version supports loading any bitcode since version 3.0. 560 561* After each X.Y release, ``compatibility.ll`` must be copied to 562 ``compatibility-X.Y.ll``. The corresponding bitcode file should be assembled 563 using the X.Y build and committed as ``compatibility-X.Y.ll.bc``. 564 565* Newer releases can ignore features from older releases, but they cannot 566 miscompile them. For example, if nsw is ever replaced with something else, 567 dropping it would be a valid way to upgrade the IR. 568 569* Debug metadata is special in that it is currently dropped during upgrades. 570 571* Non-debug metadata is defined to be safe to drop, so a valid way to upgrade 572 it is to drop it. That is not very user friendly and a bit more effort is 573 expected, but no promises are made. 574 575C API Changes 576---------------- 577 578* Stability Guarantees: The C API is, in general, a "best effort" for stability. 579 This means that we make every attempt to keep the C API stable, but that 580 stability will be limited by the abstractness of the interface and the 581 stability of the C++ API that it wraps. In practice, this means that things 582 like "create debug info" or "create this type of instruction" are likely to be 583 less stable than "take this IR file and JIT it for my current machine". 584 585* Release stability: We won't break the C API on the release branch with patches 586 that go on that branch, with the exception that we will fix an unintentional 587 C API break that will keep the release consistent with both the previous and 588 next release. 589 590* Testing: Patches to the C API are expected to come with tests just like any 591 other patch. 592 593* Including new things into the API: If an LLVM subcomponent has a C API already 594 included, then expanding that C API is acceptable. Adding C API for 595 subcomponents that don't currently have one needs to be discussed on the 596 mailing list for design and maintainability feedback prior to implementation. 597 598* Documentation: Any changes to the C API are required to be documented in the 599 release notes so that it's clear to external users who do not follow the 600 project how the C API is changing and evolving. 601 602.. _toolchain: 603 604Updating Toolchain Requirements 605------------------------------- 606 607We intend to require newer toolchains as time goes by. This means LLVM's 608codebase can use newer versions of C++ as they get standardized. Requiring newer 609toolchains to build LLVM can be painful for those building LLVM; therefore, it 610will only be done through the following process: 611 612 * It is a general goal to support LLVM and GCC versions from the last 3 years 613 at a minimum. This time-based guideline is not strict: we may support much 614 older compilers, or decide to support fewer versions. 615 616 * An RFC is sent to the `llvm-dev mailing list`_ 617 618 - Detail upsides of the version increase (e.g. which newer C++ language or 619 library features LLVM should use; avoid miscompiles in particular compiler 620 versions, etc). 621 - Detail downsides on important platforms (e.g. Ubuntu LTS status). 622 623 * Once the RFC reaches consensus, update the CMake toolchain version checks as 624 well as the :doc:`getting started<GettingStarted>` guide. This provides a 625 softer transition path for developers compiling LLVM, because the 626 error can be turned into a warning using a CMake flag. This is an important 627 step: LLVM still doesn't have code which requires the new toolchains, but it 628 soon will. If you compile LLVM but don't read the mailing list, we should 629 tell you! 630 631 * Ensure that at least one LLVM release has had this soft-error. Not all 632 developers compile LLVM top-of-tree. These release-bound developers should 633 also be told about upcoming changes. 634 635 * Turn the soft-error into a hard-error after said LLVM release has branched. 636 637 * Update the :doc:`coding standards<CodingStandards>` to allow the new 638 features we've explicitly approved in the RFC. 639 640 * Start using the new features in LLVM's codebase. 641 642Here's a `sample RFC 643<http://lists.llvm.org/pipermail/llvm-dev/2019-January/129452.html>`_ and the 644`corresponding change <https://reviews.llvm.org/D57264>`_. 645 646.. _ci-usage: 647 648Working with the CI system 649-------------------------- 650 651The main continuous integration (CI) tool for the LLVM project is the 652`LLVM Buildbot <https://lab.llvm.org/buildbot/>`_. It uses different *builders* 653to cover a wide variety of sub-projects and configurations. The builds are 654executed on different *workers*. Builders and workers are configured and 655provided by community members. 656 657The Buildbot tracks the commits on the main branch and the release branches. 658This means that patches are built and tested after they are merged to the these 659branches (aka post-merge testing). This also means it's okay to break the build 660occasionally, as it's unreasonable to expect contributors to build and test 661their patch with every possible configuration. 662 663*If your commit broke the build:* 664 665* Fix the build as soon as possible as this might block other contributors or 666 downstream users. 667* If you need more time to analyze and fix the bug, please revert your change to 668 unblock others. 669 670*If someone else broke the build and this blocks your work* 671 672* Comment on the code review in `Phabricator <https://reviews.llvm.org/>`_ 673 (if available) or email the author, explain the problem and how this impacts 674 you. Add a link to the broken build and the error message so folks can 675 understand the problem. 676* Revert the commit if this blocks your work, see revert_policy_ . 677 678*If a build/worker is permanently broken* 679 680* 1st step: contact the owner of the worker. You can find the name and contact 681 information for the *Admin* of worker on the page of the build in the 682 *Worker* tab: 683 684 .. image:: buildbot_worker_contact.png 685 686* 2nd step: If the owner does not respond or fix the worker, please escalate 687 to Galina Kostanova, the maintainer of the BuildBot master. 688* 3rd step: If Galina could not help you, please escalate to the 689 `Infrastructure Working Group <mailto:iwg@llvm.org>`_. 690 691.. _new-llvm-components: 692 693Introducing New Components into LLVM 694==================================== 695 696The LLVM community is a vibrant and exciting place to be, and we look to be 697inclusive of new projects and foster new communities, and increase 698collaboration across industry and academia. 699 700That said, we need to strike a balance between being inclusive of new ideas and 701people and the cost of ongoing maintenance that new code requires. As such, we 702have a general :doc:`support policy<SupportPolicy>` for introducing major new 703components into the LLVM world, depending on the degree of detail and 704responsibility required. *Core* projects need a higher degree of scrutiny 705than *peripheral* projects, and the latter may have additional differences. 706 707However, this is really only intended to cover common cases 708that we have seen arise: different situations are different, and we are open 709to discussing unusual cases as well - just start an RFC thread on the 710`llvm-dev mailing list`_. 711 712Adding a New Target 713------------------- 714 715LLVM is very receptive to new targets, even experimental ones, but a number of 716problems can appear when adding new large portions of code, and back-ends are 717normally added in bulk. New targets need the same level of support as other 718*core* parts of the compiler, so they are covered in the *core tier* of our 719:doc:`support policy<SupportPolicy>`. 720 721We have found that landing large pieces of new code and then trying to fix 722emergent problems in-tree is problematic for a variety of reasons. For these 723reasons, new targets are *always* added as *experimental* until they can be 724proven stable, and later moved to non-experimental. 725 726The differences between both classes are: 727 728* Experimental targets are not built by default (they need to be explicitly 729 enabled at CMake time). 730 731* Test failures, bugs, and build breakages that only appear when the 732 experimental target is enabled, caused by changes unrelated to the target, are 733 the responsibility of the community behind the target to fix. 734 735The basic rules for a back-end to be upstreamed in **experimental** mode are: 736 737* Every target must have a :ref:`code owner<code owners>`. The `CODE_OWNERS.TXT` 738 file has to be updated as part of the first merge. The code owner makes sure 739 that changes to the target get reviewed and steers the overall effort. 740 741* There must be an active community behind the target. This community 742 will help maintain the target by providing buildbots, fixing 743 bugs, answering the LLVM community's questions and making sure the new 744 target doesn't break any of the other targets, or generic code. This 745 behavior is expected to continue throughout the lifetime of the 746 target's code. 747 748* The code must be free of contentious issues, for example, large 749 changes in how the IR behaves or should be formed by the front-ends, 750 unless agreed by the majority of the community via refactoring of the 751 (:doc:`IR standard<LangRef>`) **before** the merge of the new target changes, 752 following the :ref:`IR backwards compatibility`. 753 754* The code conforms to all of the policies laid out in this developer policy 755 document, including license, patent, and coding standards. 756 757* The target should have either reasonable documentation on how it 758 works (ISA, ABI, etc.) or a publicly available simulator/hardware 759 (either free or cheap enough) - preferably both. This allows 760 developers to validate assumptions, understand constraints and review code 761 that can affect the target. 762 763In addition, the rules for a back-end to be promoted to **official** are: 764 765* The target must have addressed every other minimum requirement and 766 have been stable in tree for at least 3 months. This cool down 767 period is to make sure that the back-end and the target community can 768 endure continuous upstream development for the foreseeable future. 769 770* The target's code must have been completely adapted to this policy 771 as well as the :doc:`coding standards<CodingStandards>`. Any exceptions that 772 were made to move into experimental mode must have been fixed **before** 773 becoming official. 774 775* The test coverage needs to be broad and well written (small tests, 776 well documented). The build target ``check-all`` must pass with the 777 new target built, and where applicable, the ``test-suite`` must also 778 pass without errors, in at least one configuration (publicly 779 demonstrated, for example, via buildbots). 780 781* Public buildbots need to be created and actively maintained, unless 782 the target requires no additional buildbots (ex. ``check-all`` covers 783 all tests). The more relevant and public the new target's CI infrastructure 784 is, the more the LLVM community will embrace it. 785 786To **continue** as a supported and official target: 787 788* The maintainer(s) must continue following these rules throughout the lifetime 789 of the target. Continuous violations of aforementioned rules and policies 790 could lead to complete removal of the target from the code base. 791 792* Degradation in support, documentation or test coverage will make the target as 793 nuisance to other targets and be considered a candidate for deprecation and 794 ultimately removed. 795 796In essences, these rules are necessary for targets to gain and retain their 797status, but also markers to define bit-rot, and will be used to clean up the 798tree from unmaintained targets. 799 800Adding an Established Project To the LLVM Monorepo 801-------------------------------------------------- 802 803The `LLVM monorepo <https://github.com/llvm/llvm-project>`_ is the centerpoint 804of development in the LLVM world, and has all of the primary LLVM components, 805including the LLVM optimizer and code generators, Clang, LLDB, etc. `Monorepos 806in general <https://en.wikipedia.org/wiki/Monorepo>`_ are great because they 807allow atomic commits to the project, simplify CI, and make it easier for 808subcommunities to collaborate. 809 810Like new targets, most projects already in the monorepo are considered to be in 811the *core tier* of our :doc:`support policy<SupportPolicy>`. The burden to add 812things to the LLVM monorepo needs to be very high - code that is added to this 813repository is checked out by everyone in the community. As such, we hold 814components to a high bar similar to "official targets", they: 815 816 * Must be generally aligned with the mission of the LLVM project to advance 817 compilers, languages, tools, runtimes, etc. 818 * Must conform to all of the policies laid out in this developer policy 819 document, including license, patent, coding standards, and code of conduct. 820 * Must have an active community that maintains the code, including established 821 code owners. 822 * Should have reasonable documentation about how it works, including a high 823 quality README file. 824 * Should have CI to catch breakage within the project itself or due to 825 underlying LLVM dependencies. 826 * Should have code free of issues the community finds contentious, or be on a 827 clear path to resolving them. 828 * Must be proposed through the LLVM RFC process, and have its addition approved 829 by the LLVM community - this ultimately mediates the resolution of the 830 "should" concerns above. 831 832If you have a project that you think would make sense to add to the LLVM 833monorepo, please start an RFC thread on the `llvm-dev mailing list`_ to kick off 834the discussion. This process can take some time and iteration - please don’t 835be discouraged or intimidated by that! 836 837If you have an earlier stage project that you think is aligned with LLVM, please 838see the "Incubating New Projects" section. 839 840Incubating New Projects 841----------------------- 842 843The burden to add a new project to the LLVM monorepo is intentionally very high, 844but that can have a chilling effect on new and innovative projects. To help 845foster these sorts of projects, LLVM supports an "incubator" process that is 846much easier to get started with. It provides space for potentially valuable, 847new top-level and sub-projects to reach a critical mass before they have enough 848code to prove their utility and grow a community. This also allows 849collaboration between teams that already have permissions to make contributions 850to projects under the LLVM umbrella. 851 852Projects which can be considered for the LLVM incubator meet the following 853criteria: 854 855 * Must be generally aligned with the mission of the LLVM project to advance 856 compilers, languages, tools, runtimes, etc. 857 * Must conform to the license, patent, and code of conduct policies laid out 858 in this developer policy document. 859 * Must have a documented charter and development plan, e.g. in the form of a 860 README file, mission statement, and/or manifesto. 861 * Should conform to coding standards, incremental development process, and 862 other expectations. 863 * Should have a sense of the community that it hopes to eventually foster, and 864 there should be interest from members with different affiliations / 865 organizations. 866 * Should have a feasible path to eventually graduate as a dedicated top-level 867 or sub-project within the `LLVM monorepo 868 <https://github.com/llvm/llvm-project>`_. 869 * Should include a notice (e.g. in the project README or web page) that the 870 project is in ‘incubation status’ and is not included in LLVM releases (see 871 suggested wording below). 872 * Must be proposed through the LLVM RFC process, and have its addition 873 approved by the LLVM community - this ultimately mediates the resolution of 874 the "should" concerns above. 875 876That said, the project need not have any code to get started, and need not have 877an established community at all! Furthermore, incubating projects may pass 878through transient states that violate the "Should" guidelines above, or would 879otherwise make them unsuitable for direct inclusion in the monorepo (e.g. 880dependencies that have not yet been factored appropriately, leveraging 881experimental components or APIs that are not yet upstream, etc). 882 883When approved, the llvm-admin group can grant the new project: 884 * A new repository in the LLVM Github Organization - but not the LLVM monorepo. 885 * New mailing list, discourse forum, and/or discord chat hosted with other LLVM 886 forums. 887 * Other infrastructure integration can be discussed on a case-by-case basis. 888 889Graduation to the mono-repo would follow existing processes and standards for 890becoming a first-class part of the monorepo. Similarly, an incubating project 891may be eventually retired, but no process has been established for that yet. If 892and when this comes up, please start an RFC discussion on llvm-dev. 893 894This process is very new - please expect the details to change, it is always 895safe to ask on the `llvm-dev mailing list`_ about this. 896 897Suggested disclaimer for the project README and the main project web page: 898 899:: 900 901 This project is participating in the LLVM Incubator process: as such, it is 902 not part of any official LLVM release. While incubation status is not 903 necessarily a reflection of the completeness or stability of the code, it 904 does indicate that the project is not yet endorsed as a component of LLVM. 905 906.. _copyright-license-patents: 907 908Copyright, License, and Patents 909=============================== 910 911.. note:: 912 913 This section deals with legal matters but does not provide legal advice. We 914 are not lawyers --- please seek legal counsel from a licensed attorney. 915 916This section addresses the issues of copyright, license and patents for the LLVM 917project. The copyright for the code is held by the contributors of 918the code. The code is licensed under permissive `open source licensing terms`_, 919namely the Apache-2.0 with LLVM-exception license, which includes a copyright 920and `patent license`_. When you contribute code to the LLVM project, you 921license it under these terms. 922 923If you have questions or comments about these topics, please contact the 924`LLVM Developer's Mailing List <mailto:llvm-dev@lists.llvm.org>`_. However, 925please realize that most compiler developers are not lawyers, and therefore you 926will not be getting official legal advice. 927 928Copyright 929--------- 930 931The LLVM project does not collect copyright assignments, which means that the 932copyright for the code in the project is held by the respective contributors. 933Because you (or your company) 934retain ownership of the code you contribute, you know it may only be used under 935the terms of the open source license you contributed it under: the license for 936your contributions cannot be changed in the future without your approval. 937 938Because the LLVM project does not require copyright assignments, changing the 939LLVM license requires tracking down the 940contributors to LLVM and getting them to agree that a license change is 941acceptable for their contributions. We feel that a high burden for relicensing 942is good for the project, because contributors do not have to fear that their 943code will be used in a way with which they disagree. 944 945Relicensing 946----------- 947 948The last paragraph notwithstanding, the LLVM Project is in the middle of a large 949effort to change licenses, which aims to solve several problems: 950 951* The old licenses made it difficult to move code from (e.g.) the compiler to 952 runtime libraries, because runtime libraries used a different license from the 953 rest of the compiler. 954* Some contributions were not submitted to LLVM due to concerns that 955 the patent grant required by the project was overly broad. 956* The patent grant was unique to the LLVM Project, not written by a lawyer, and 957 was difficult to determine what protection was provided (if any). 958 959The scope of relicensing is all code that is considered part of the LLVM 960project, including the main LLVM repository, runtime libraries (compiler_rt, 961OpenMP, etc), Polly, and all other subprojects. There are a few exceptions: 962 963* Code imported from other projects (e.g. Google Test, Autoconf, etc) will 964 remain as it is. This code isn't developed as part of the LLVM project, it 965 is used by LLVM. 966* Some subprojects are impractical or uninteresting to relicense (e.g. llvm-gcc 967 and dragonegg). These will be split off from the LLVM project (e.g. to 968 separate GitHub projects), allowing interested people to continue their 969 development elsewhere. 970 971To relicense LLVM, we will be seeking approval from all of the copyright holders 972of code in the repository, or potentially remove/rewrite code if we cannot. 973This is a large 974and challenging project which will take a significant amount of time to 975complete. In the interim, **all contributions to the project will be made under 976the terms of both the new license and the legacy license scheme** (each of which 977is described below). The exception to this is the legacy patent grant, which 978will not be required for new contributions. 979 980When all of the code in the project has been converted to the new license or 981removed, we will drop the requirement to contribute under the legacy license. 982This will achieve the goal of having 983a single standardized license for the entire codebase. 984 985If you are a prior contributor to LLVM and have not done so already, please do 986*TODO* to allow us to use your code. *Add a link to a separate page here, which 987is probably a click through web form or something like that. Details to be 988determined later*. 989 990 991.. _open source licensing terms: 992 993New LLVM Project License Framework 994---------------------------------- 995 996Contributions to LLVM are licensed under the `Apache License, Version 2.0 997<https://www.apache.org/licenses/LICENSE-2.0>`_, with two limited 998exceptions intended to ensure that LLVM is very permissively licensed. 999Collectively, the name of this license is "Apache 2.0 License with LLVM 1000exceptions". The exceptions read: 1001 1002:: 1003 1004 ---- LLVM Exceptions to the Apache 2.0 License ---- 1005 1006 As an exception, if, as a result of your compiling your source code, portions 1007 of this Software are embedded into an Object form of such source code, you 1008 may redistribute such embedded portions in such Object form without complying 1009 with the conditions of Sections 4(a), 4(b) and 4(d) of the License. 1010 1011 In addition, if you combine or link compiled forms of this Software with 1012 software that is licensed under the GPLv2 ("Combined Software") and if a 1013 court of competent jurisdiction determines that the patent provision (Section 1014 3), the indemnity provision (Section 9) or other Section of the License 1015 conflicts with the conditions of the GPLv2, you may retroactively and 1016 prospectively choose to deem waived or otherwise exclude such Section(s) of 1017 the License, but only in their entirety and only with respect to the Combined 1018 Software. 1019 1020 1021We intend to keep LLVM perpetually open source and available under a permissive 1022license - this fosters the widest adoption of LLVM by 1023**allowing commercial products to be derived from LLVM** with few restrictions 1024and without a requirement for making any derived works also open source. In 1025particular, LLVM's license is not a "copyleft" license like the GPL. 1026 1027The "Apache 2.0 License with LLVM exceptions" allows you to: 1028 1029* freely download and use LLVM (in whole or in part) for personal, internal, or 1030 commercial purposes. 1031* include LLVM in packages or distributions you create. 1032* combine LLVM with code licensed under every other major open source 1033 license (including BSD, MIT, GPLv2, GPLv3...). 1034* make changes to LLVM code without being required to contribute it back 1035 to the project - contributions are appreciated though! 1036 1037However, it imposes these limitations on you: 1038 1039* You must retain the copyright notice if you redistribute LLVM: You cannot 1040 strip the copyright headers off or replace them with your own. 1041* Binaries that include LLVM must reproduce the copyright notice (e.g. in an 1042 included README file or in an "About" box), unless the LLVM code was added as 1043 a by-product of compilation. For example, if an LLVM runtime library like 1044 compiler_rt or libc++ was automatically included into your application by the 1045 compiler, you do not need to attribute it. 1046* You can't use our names to promote your products (LLVM derived or not) - 1047 though you can make truthful statements about your use of the LLVM code, 1048 without implying our sponsorship. 1049* There's no warranty on LLVM at all. 1050 1051We want LLVM code to be widely used, and believe that this provides a model that 1052is great for contributors and users of the project. For more information about 1053the Apache 2.0 License, please see the `Apache License FAQ 1054<http://www.apache.org/foundation/license-faq.html>`_, maintained by the 1055Apache Project. 1056 1057 1058.. note:: 1059 1060 The LLVM Project includes some really old subprojects (dragonegg, 1061 llvm-gcc-4.0, and llvm-gcc-4.2), which are licensed under **GPL 1062 licenses**. This code is not actively maintained - it does not even 1063 build successfully. This code is cleanly separated into distinct SVN 1064 repositories from the rest of LLVM, and the LICENSE.txt files specifically 1065 indicate that they contain GPL code. When LLVM transitions from SVN to Git, 1066 we plan to drop these code bases from the new repository structure. 1067 1068 1069.. _patent license: 1070 1071Patents 1072------- 1073 1074Section 3 of the Apache 2.0 license is a patent grant under which 1075contributors of code to the project contribute the rights to use any of 1076their patents that would otherwise be infringed by that code contribution 1077(protecting uses of that code). Further, the patent grant is revoked 1078from anyone who files a patent lawsuit about code in LLVM - this protects the 1079community by providing a "patent commons" for the code base and reducing the 1080odds of patent lawsuits in general. 1081 1082The license specifically scopes which patents are included with code 1083contributions. To help explain this, the `Apache License FAQ 1084<http://www.apache.org/foundation/license-faq.html>`_ explains this scope using 1085some questions and answers, which we reproduce here for your convenience (for 1086reference, the "ASF" is the Apache Software Foundation, the guidance still 1087holds though):: 1088 1089 Q1: If I own a patent and contribute to a Work, and, at the time my 1090 contribution is included in that Work, none of my patent's claims are subject 1091 to Apache's Grant of Patent License, is there a way any of those claims would 1092 later become subject to the Grant of Patent License solely due to subsequent 1093 contributions by other parties who are not licensees of that patent. 1094 1095 A1: No. 1096 1097 Q2: If at any time after my contribution, I am able to license other patent 1098 claims that would have been subject to Apache's Grant of Patent License if 1099 they were licensable by me at the time of my contribution, do those other 1100 claims become subject to the Grant of Patent License? 1101 1102 A2: Yes. 1103 1104 Q3: If I own or control a licensable patent and contribute code to a specific 1105 Apache product, which of my patent claims are subject to Apache's Grant of 1106 Patent License? 1107 1108 A3: The only patent claims that are licensed to the ASF are those you own or 1109 have the right to license that read on your contribution or on the 1110 combination of your contribution with the specific Apache product to which 1111 you contributed as it existed at the time of your contribution. No additional 1112 patent claims become licensed as a result of subsequent combinations of your 1113 contribution with any other software. Note, however, that licensable patent 1114 claims include those that you acquire in the future, as long as they read on 1115 your original contribution as made at the original time. Once a patent claim 1116 is subject to Apache's Grant of Patent License, it is licensed under the 1117 terms of that Grant to the ASF and to recipients of any software distributed 1118 by the ASF for any Apache software product whatsoever. 1119 1120.. _legacy: 1121 1122Legacy License Structure 1123------------------------ 1124 1125.. note:: 1126 The code base was previously licensed under the Terms described here. 1127 We are in the middle of relicensing to a new approach (described above), but 1128 until this effort is complete, the code is also still available under these 1129 terms. Once we finish the relicensing project, new versions of the code will 1130 not be available under these terms. However, nothing takes away your right 1131 to use old versions under the licensing terms under which they were 1132 originally released. 1133 1134We intend to keep LLVM perpetually open source and to use a permissive open 1135source license. The code in 1136LLVM is available under the `University of Illinois/NCSA Open Source License 1137<http://www.opensource.org/licenses/UoI-NCSA.php>`_, which boils down to 1138this: 1139 1140* You can freely distribute LLVM. 1141* You must retain the copyright notice if you redistribute LLVM. 1142* Binaries derived from LLVM must reproduce the copyright notice (e.g. in an 1143 included README file). 1144* You can't use our names to promote your LLVM derived products. 1145* There's no warranty on LLVM at all. 1146 1147We believe this fosters the widest adoption of LLVM because it **allows 1148commercial products to be derived from LLVM** with few restrictions and without 1149a requirement for making any derived works also open source (i.e. LLVM's 1150license is not a "copyleft" license like the GPL). We suggest that you read the 1151`License <http://www.opensource.org/licenses/UoI-NCSA.php>`_ if further 1152clarification is needed. 1153 1154In addition to the UIUC license, the runtime library components of LLVM 1155(**compiler_rt, libc++, and libclc**) are also licensed under the `MIT License 1156<http://www.opensource.org/licenses/mit-license.php>`_, which does not contain 1157the binary redistribution clause. As a user of these runtime libraries, it 1158means that you can choose to use the code under either license (and thus don't 1159need the binary redistribution clause), and as a contributor to the code that 1160you agree that any contributions to these libraries be licensed under both 1161licenses. We feel that this is important for runtime libraries, because they 1162are implicitly linked into applications and therefore should not subject those 1163applications to the binary redistribution clause. This also means that it is ok 1164to move code from (e.g.) libc++ to the LLVM core without concern, but that code 1165cannot be moved from the LLVM core to libc++ without the copyright owner's 1166permission. 1167 1168.. _llvm-dev mailing list: http://lists.llvm.org/mailman/listinfo/llvm-dev 1169