Lines Matching full:to
15 to eliminate miscommunication, rework, and confusion that might arise from the
17 we hope each developer can know ahead of time what to expect when making LLVM
21 This policy is also designed to accomplish the following objectives:
23 #. Attract both users and developers to the LLVM project.
30 policies <copyright-license-patents>` with contributors to the project.
32 This policy is aimed at frequent contributors to LLVM. People interested in
33 contributing one-off patches can do so in an informal way by sending them to the
36 developer to see it through the process.
41 This section contains policies that pertain to frequent LLVM developers. We
42 always welcome `one-off patches`_ from people who do not routinely contribute to
43 LLVM, but we expect more from frequent contributors to keep the system as
44 efficient as possible for everyone. Frequent LLVM contributors are expected to
45 meet the following requirements in order for LLVM to maintain a high standard of
52 to the categories of interest for notifications.
54 Paying attention to changes being made by others is a good way to see what other people
57 Contibutions to the project are made through :ref:`GitHub Pull Requests <github-reviews>`.
58 You can subscribe to notification for areas of the codebase by joining
63 You can also subscribe to the "commits" mailing list for a subproject you're interested in,
74 You may also subscribe to the `llvm-bugs
75 <http://lists.llvm.org/mailman/listinfo/llvm-bugs>`_ email list to keep track
89 When making a patch for review, the goal is to make it as easy for the reviewer
90 to read it as possible. As such, we recommend that you:
93 of LLVM. This makes it easy to apply the patch. For information on how to
105 notices to the patches themselves. These notices conflict with the LLVM
113 The LLVM project uses email to communicate to contributors outside of the
115 infrastructure uses emails to contact contributors about build and test
118 Therefore, the LLVM community requires contributors to have a public
128 LLVM has a code-review policy. Code review is one way to increase the quality of
137 Please help notify users and vendors of potential disruptions when upgrading to
139 to be removed in the future, removing an already-deprecated feature, upgrading a
140 diagnostic from a warning to an error, switching important default behavior, or
141 any other potentially disruptive situation thought to be worth raising
148 This section contains old information that needs to be updated.
151 "vendors" group to the review for their awareness. The purpose of these
152 groups is to give vendors early notice that potentially disruptive changes
154 testing feedback on the changes to alert us to unacceptable breakages. The
163 * When committing the change to the repository, add appropriate information
164 about the potentially breaking changes to the ``Potentially Breaking Changes``
168 to share with users. This helps users to learn about potential issues with
169 upgrading to that release.
171 * After the change has been committed to the repository, the potentially
172 disruptive changes described in the release notes should be posted to the
175 and a label specific to the project (such as ``clang``, ``llvm``, etc). This
176 is another mechanism by which we can give pre-release notice to users about
177 potentially disruptive changes. It is a lower-traffic alternative to the
178 joining "vendors" group. To automatically be notified of new announcements
179 with the ``potentially-breaking`` label, go to your user preferences page in
180 Discourse, and add the label to one of the watch categories under
188 The LLVM Project aims to evolve features quickly while continually being in a
189 release-ready state. In order to accomplish this, the project needs volunteers
190 willing to do the less glamorous work to ensure we produce robust, high-quality
194 to take on additional community responsibilities beyond code contributions.
198 Maintainers are volunteering to take on the following shared responsibilities
203 * help to confirm and comment on issues,
205 maintainers (and other reviewers) to come to a consensus on how best to
218 maintainer to reach out to, a lead maintainer is always a good choice
219 to reach out to. If a project has no active lead maintainers, it may be a
221 started on Discourse to find a new, active lead maintainer or whether the
224 All contributors with commit access to the LLVM Project are eligible to be a
225 maintainer. However, we are looking for people who can commit to:
234 Therefore, we want as little friction as possible for someone to become a
235 maintainer or to step down as a maintainer.
237 *To become a new maintainer*, you can volunteer yourself by posting a PR which
238 adds yourself to the area(s) you are volunteering for. Alternatively, an
240 explicitly accept the PR so that it's clear they agree to volunteer within the
242 the same project vouches for their ability to perform the responsibilities and
245 *To step down as a maintainer*, you can move your name to the "inactive
249 of time can be moved to the "inactive maintainers" section by another active
252 please post on Discourse to solicit wider community feedback about the removal
254 with the inactive maintainer before such removal to avoid accidental
260 *To resume activities as a maintainer*, you can post a PR moving your name from
261 the "inactive maintainers" section of the ``Maintainers.rst`` file to the
271 Developers are required to create test cases for any bugs fixed and any new
274 * All feature and regression test cases are added to the ``llvm/test``
281 by :doc:`bugpoint <Bugpoint>` or manually. It is unacceptable to place an
282 entire failing program into ``llvm/test`` as this creates a *time-to-test*
285 * Avoid adding links to resources that are not available to the entire
286 community, such as links to private bug trackers, internal corporate
287 documentation, etc. Instead, add sufficient comments to the test to provide
292 etc) should be added to the ``llvm-test`` test suite. The llvm-test suite is
299 Many projects in LLVM communicate important changes to users through release
300 notes, typically found in ``docs/ReleaseNotes.rst`` for the project. Changes to
301 a project that are user-facing, or that users may wish to know about, should be
302 added to the project's release notes at the author's or code reviewer's
310 to the issue fixed in the bug database).
314 * Notifying users about a potentially disruptive change expected to be made in
316 release note should be added to a ``Potentially Breaking Changes`` section of
317 the notes with sufficient information and examples to demonstrate the
318 potential disruption. Additionally, any new entries to this section should be
322 Code reviewers are encouraged to request a release note if they think one is
329 committed to the main development branch are:
331 #. Code must adhere to the `LLVM Coding Standards <CodingStandards.html>`_.
345 #. Ensure that links in source code and test files point to publicly available
346 resources and are used primarily to add additional information rather than
347 to supply critical context. The surrounding comments should be sufficient
348 to provide the context behind such links.
364 * You are expected to address any `GitHub Issues <https://github.com/llvm/llvm-project/issues>`_ that
367 We prefer for this to be handled before submission but understand that it isn't
368 possible to test all of this for every submission. Our build bots and nightly
370 to check the nightly testers for regressions the day after your change. Build
372 failure. You are expected to check the build bot messages to see if they are
377 progress. The developer is welcome to re-commit the change after the problem has
386 you follow these guidelines to help review, search in logs, email formatting
387 and so on. These guidelines are very similar to rules used by other open source
390 Most importantly, the contents of the message should be carefully written to
395 all there is to the change.
402 set to the original author and the 'Committer' property is set to yourself.
403 You can use a command similar to
404 ``git commit --amend --author="John Doe <jdoe@llvm.org>"`` to correct the
407 migrated to git.
410 tag 'Co-authored-by:' to list the additional authors
413 * The title should be concise. Because all commits are emailed to the list with
417 * When the changes are restricted to a specific part of the code (e.g. a
418 back-end or optimization pass), it is customary to add a tag to the
426 reasoning. Unless it is required to understand the change, examples,
427 code snippets and gory details should be left to bug comments, web
438 * If the patch has been reviewed, add a link to its review page, as shown
440 If the patch fixes a bug in GitHub Issues, we encourage adding a reference to
444 * It is also acceptable to add other metadata to the commit message to automate
446 links to resources that are not available to the entire community. However,
453 omissions can be handled by sending a reply to the commits mailing list.
461 allowing rapid iterative development. As such, we tend to make much heavier
462 use of reverts to keep the tree healthy than some other open source projects,
467 * Remember, it is normal and healthy to have patches reverted. Having a patch
471 * If you need more information to address the problem, please follow up in the
477 We strongly encourage "revert to green" as opposed to "fixing forward". We
486 * If you are asked to revert by another contributor, please revert and discuss
493 guidelines, we encourage other contributors to do so as a courtesy to the
496 expect contributors to be always available, and the assurance that a
497 problematic patch will be reverted and we can return to it at our next
503 the commit thread asking for assistance. We aren't trying to enumerate
507 instead of improving them. We expect reasonable judgment to ensure that
511 * It is customary to respond to the original commit email mentioning the
512 revert. This serves as both a notice to the original author that their
514 * Ideally, you should have a publicly reproducible test case ready to share.
516 in PRs. We encourage the reverter to minimize the test case and to prune
520 * It is not considered reasonable to revert without at least the promise to
521 provide a means for the patch author to debug the root issue. If a situation
523 requires hardware patch author doesn't have access to, sharp regression in
524 compile time of internal workload, etc.), the reverter is expected to be
525 proactive about working with the patch author to debug and test candidate
529 should not be. Where exactly the transition point is is hard to say, but
531 we encourage you to reply to the commit thread, give the author a bit to
532 respond, and then proceed with the revert if the author doesn't seem to be
534 * When re-applying a reverted patch, the commit message should be updated to
542 We grant commit access to contributors that can provide a valid justification.
543 If you would like commit access, please use this `link <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?>`_ to file
546 the issue description. If approved, a GitHub invitation will be sent to your
547 GitHub account. In case you don't get notification from GitHub, go to
551 Prior to obtaining commit access, it is common practice to request that
553 provide the name and email address you would like to use in the Author
559 commit to require a moderator to approve the email, so do not be concerned if a
564 #. You are granted *commit-after-approval* to all parts of LLVM. For
565 information on how to get approval for a patch, please see :doc:`CodeReview`.
568 #. You are allowed to commit patches without approval which you think are
569 obvious. This is clearly a subjective decision --- we simply expect you to
573 code you plan to make subsequent changes to. Also, try to separate
577 is not intended to change functionality, usually by stating it is
580 #. You are allowed to commit patches without approval to those portions of LLVM
587 cause commit access to be revoked.
589 In any case, your changes are still subject to `code review`_ (either before or
591 encouraged to review other peoples' patches as well, but you aren't required
592 to do so.
600 to LLVM, they should inform the community with a post to the `LLVM Discourse forums`_, to the extent
601 possible. The reason for this is to:
603 #. keep the community informed about future changes to LLVM,
611 The design of LLVM is carefully controlled to ensure that all the pieces fit
612 together well and are as consistent as possible. If you plan to make a major
613 change to the way LLVM works or want to add a major new extension, it is a good
614 idea to get consensus with the development community before you start working on
633 #. Other people in the community tend to ignore work on branches.
636 extremely difficult to `code review`_.
642 changes increases the odds that any of the work will be committed to the main
645 To address these problems, LLVM uses an incremental development style and we
646 require contributors to follow this practice when making a large/invasive
658 * Each change in the set can be stand alone (e.g. to fix a bug), or part of a
666 * Often, an independent precursor to a big change is to add a new API and slowly
667 migrate clients to use the new API. Each change to use the new API is often
669 and used, it is much easier to replace the underlying implementation of the
674 sure to first `discuss the change/gather consensus`_ then ask about the best way
675 to go about making the change.
680 When contributors submit a patch to an LLVM project, other developers with
682 progression of code review, etc.). When doing so, it is important to retain
683 correct attribution of contributions to their contributors. However, we do not
684 want the source code to be littered with random attributions "this code written
690 to the source code.
693 patch to the project or you have been authorized to submit them on their behalf
694 (you work together and your company authorized you to contribute the patches,
695 etc.). The author should first submit them to the relevant project's commit
697 a patch privately, encourage them to submit it to the appropriate list first.
701 attribution mechanism. The previous method was to include "Patch by John Doe."
708 The goal of a ban is to protect people in the community from having to interact
719 When in doubt how to act in a specific instance, please reach out to
728 When the IR format has to be changed, keep in mind that we try to maintain some
735 * Additions and changes to the IR should be reflected in
740 * After each X.Y release, ``compatibility.ll`` must be copied to
746 dropping it would be a valid way to upgrade the IR.
750 * Non-debug metadata is defined to be safe to drop, so a valid way to upgrade
751 it is to drop it. That is not very user friendly and a bit more effort is
758 This means that we make every attempt to keep the C API stable, but that
761 like "create debug info" or "create this type of instruction" are likely to be
769 * Testing: Patches to the C API are expected to come with tests just like any
774 subcomponents that don't currently have one needs to be discussed on the
775 `LLVM Discourse forums`_ for design and maintainability feedback prior to implementation.
777 * Documentation: Any changes to the C API are required to be documented in the
778 release notes so that it's clear to external users who do not follow the
786 We intend to require newer toolchains as time goes by. This means LLVM's
788 toolchains to build LLVM can be painful for those building LLVM; therefore, it
791 * It is a general goal to support LLVM and GCC versions from the last 3 years
793 older compilers, or decide to support fewer versions.
795 * An RFC is sent to the `LLVM Discourse forums`_
816 * Update the :doc:`coding standards<CodingStandards>` to allow the new
832 to cover a wide variety of sub-projects and configurations. The builds are
837 This means that patches are built and tested after they are merged to the these
838 branches (aka post-merge testing). This also means it's okay to break the build
839 occasionally, as it's unreasonable to expect contributors to build and test
846 * If you need more time to analyze and fix the bug, please revert your change to
853 you. Add a link to the broken build and the error message so folks can
866 to Galina Kostanova, the maintainer of the BuildBot master.
867 * 3rd step: If Galina could not help you, please escalate to the
875 The LLVM community is a vibrant and exciting place to be, and we look to be
879 That said, we need to strike a balance between being inclusive of new ideas and
886 However, this is really only intended to cover common cases
888 to discussing unusual cases as well - just start an RFC thread on the
894 LLVM is very receptive to new targets, even experimental ones, but a number of
900 We have found that landing large pieces of new code and then trying to fix
903 proven stable, and later moved to non-experimental.
907 * Experimental targets are not built by default (they need to be explicitly
911 experimental target is enabled, caused by changes unrelated to the target, are
912 the responsibility of the community behind the target to fix.
914 The basic rules for a back-end to be upstreamed in **experimental** mode are:
917 `Maintainers.rst` file has to be updated as part of the first merge. These
918 maintainers make sure that changes to the target get reviewed and steers the
925 behavior is expected to continue throughout the lifetime of the
934 * The code conforms to all of the policies laid out in this developer policy
940 developers to validate assumptions, understand constraints and review code
943 In addition, the rules for a back-end to be promoted to **official** are:
947 period is to make sure that the back-end and the target community can
950 * The target's code must have been completely adapted to this policy
952 were made to move into experimental mode must have been fixed **before**
955 * The test coverage needs to be broad and well written (small tests,
961 * Public buildbots need to be created and actively maintained, unless
966 To **continue** as a supported and official target:
970 could lead to complete removal of the target from the code base.
973 nuisance to other targets and be considered a candidate for deprecation and
976 In essence, these rules are necessary for targets to gain and retain their
977 status, but also markers to define bit-rot, and will be used to clean up the
980 Those wishing to add a new target to LLVM must follow the procedure below:
985 2. Send a request for comment (RFC) to the `LLVM Discourse forums`_ describing
987 done and will need to be done to accommodate the official target requirements.
988 Make sure to expose any and all controversial issues, changes needed in the
991 actual patches (but they can be prepared before, to support the RFC). Create
992 a sequence of N patches, numbered '1/N' to 'N/N' (make sure N is an actual
995 clang and LLVM. The following patches add TableGen infrastructure to describe
996 the target and lower instructions to assembly. The final patch must show that
997 the target can lower correctly with extensive LIT tests (IR to MIR, MIR to
1000 approved that the whole set can be merged in one go. This is to guarantee
1003 start working asynchronously on the target to complete support. They should
1004 still seek review from those who helped them in the initial phase, to make
1007 should request the target to be enabled by default by sending another RFC to
1010 Adding an Established Project To the LLVM Monorepo
1017 allow atomic commits to the project, simplify CI, and make it easier for
1018 subcommunities to collaborate.
1020 Like new targets, most projects already in the monorepo are considered to be in
1021 the *core tier* of our :doc:`support policy<SupportPolicy>`. The burden to add
1022 things to the LLVM monorepo needs to be very high - code that is added to this
1024 components to a high bar similar to "official targets", they:
1026 * Must be generally aligned with the mission of the LLVM project to advance
1028 * Must conform to all of the policies laid out in this developer policy
1034 * Should have CI to catch breakage within the project itself or due to
1037 clear path to resolving them.
1042 If you have a project that you think would make sense to add to the LLVM
1043 monorepo, please start an RFC topic on the `LLVM Discourse forums`_ to kick off
1053 The burden to add a new project to the LLVM monorepo is intentionally very high,
1054 but that can have a chilling effect on new and innovative projects. To help
1056 much easier to get started with. It provides space for potentially valuable,
1057 new top-level and sub-projects to reach a critical mass before they have enough
1058 code to prove their utility and grow a community. This also allows
1059 collaboration between teams that already have permissions to make contributions
1060 to projects under the LLVM umbrella.
1065 * Must be generally aligned with the mission of the LLVM project to advance
1067 * Must conform to the license, patent, and code of conduct policies laid out
1071 * Should conform to coding standards, incremental development process, and
1073 * Should have a sense of the community that it hopes to eventually foster, and
1076 * Should have a feasible path to eventually graduate as a dedicated top-level
1086 That said, the project need not have any code to get started, and need not have
1099 Graduation to the mono-repo would follow existing processes and standards for
1104 This process is very new - please expect the details to change, it is always
1105 safe to ask on the `LLVM Discourse forums`_ about this.
1130 and `patent license`_. When you contribute code to the LLVM project, you
1134 to the codebase. However, this may only be done with approval of the LLVM
1136 process to take at least 4-6 weeks. If you would like to contribute code
1138 you want to contribute and email board@llvm.org requesting a review.
1159 contributors to LLVM and getting them to agree that a license change is
1161 is good for the project, because contributors do not have to fear that their
1172 way to track contributions is through revision control history.
1174 changes to authors other than the committer.
1180 effort to change licenses, which aims to solve several problems:
1182 * The old licenses made it difficult to move code from (e.g.) the compiler to
1185 * Some contributions were not submitted to LLVM due to concerns that
1187 * The patent grant was unique to the LLVM Project, not written by a lawyer, and
1188 was difficult to determine what protection was provided (if any).
1197 * Some subprojects are impractical or uninteresting to relicense (e.g. llvm-gcc
1198 and dragonegg). These will be split off from the LLVM project (e.g. to
1199 separate GitHub projects), allowing interested people to continue their
1202 To relicense LLVM, we will be seeking approval from all of the copyright holders
1205 and challenging project which will take a significant amount of time to
1208 Starting on 2024-06-01 (first of June 2024), new contributions only need to
1210 Before this date, the project required all contributions to be made under
1213 If you are a contributor to LLVM with contributions committed before 2019-01-19
1216 Relicensing Agreement" to relicense your contributions under the new license.
1224 Contributions to LLVM are licensed under the `Apache License, Version 2.0
1226 exceptions intended to ensure that LLVM is very permissively licensed.
1232 ---- LLVM Exceptions to the Apache 2.0 License ----
1244 prospectively choose to deem waived or otherwise exclude such Section(s) of
1245 the License, but only in their entirety and only with respect to the Combined
1249 We intend to keep LLVM perpetually open source and available under a permissive
1251 **allowing commercial products to be derived from LLVM** with few restrictions
1255 The "Apache 2.0 License with LLVM exceptions" allows you to:
1262 * make changes to LLVM code without being required to contribute it back
1263 to the project - contributions are appreciated though!
1273 compiler, you do not need to attribute it.
1274 * You can't use our names to promote your products (LLVM derived or not) -
1279 We want LLVM code to be widely used, and believe that this provides a model that
1291 contributors of code to the project contribute the rights to use any of
1299 contributions. To help explain this, the `Apache License FAQ
1305 Q1: If I own a patent and contribute to a Work, and, at the time my
1307 to Apache's Grant of Patent License, is there a way any of those claims would
1308 later become subject to the Grant of Patent License solely due to subsequent
1313 Q2: If at any time after my contribution, I am able to license other patent
1314 claims that would have been subject to Apache's Grant of Patent License if
1316 claims become subject to the Grant of Patent License?
1320 Q3: If I own or control a licensable patent and contribute code to a specific
1321 Apache product, which of my patent claims are subject to Apache's Grant of
1324 A3: The only patent claims that are licensed to the ASF are those you own or
1325 have the right to license that read on your contribution or on the
1326 combination of your contribution with the specific Apache product to which
1332 is subject to Apache's Grant of Patent License, it is licensed under the
1333 terms of that Grant to the ASF and to recipients of any software distributed
1343 We are in the middle of relicensing to a new approach (described above).
1344 More than 99% of all contributions made to LLVM are covered by the Apache-2.0
1349 We intend to keep LLVM perpetually open source and to use a permissive open
1352 <http://www.opensource.org/licenses/UoI-NCSA.php>`_, which boils down to
1359 * You can't use our names to promote your LLVM derived products.
1363 commercial products to be derived from LLVM** with few restrictions and without
1369 In addition to the UIUC license, the runtime library components of LLVM
1373 means that you can choose to use the code under either license (and thus don't
1374 need the binary redistribution clause), and as a contributor to the code that
1375 you agree that any contributions to these libraries be licensed under both
1378 applications to the binary redistribution clause. This also means that it is ok
1379 to move code from (e.g.) libc++ to the LLVM core without concern, but that code
1380 cannot be moved from the LLVM core to libc++ without the copyright owner's
1389 yet to be answered. Our policy on AI tools is guided by our copyright policy:
1390 Contributors are responsible for ensuring that they have the right to contribute
1392 employer, or their collaborators hold the copyright. Using AI tools to
1397 As such, the LLVM policy is that contributors are permitted to use artificial
1398 intelligence tools to produce contributions, provided that they have the right
1399 to license that code under the project license. Contributions found to violate
1403 considered responsible for their contributions. We encourage contributors to
1404 review all generated code before sending it for review to verify its
1405 correctness and to understand it so that they can answer questions during code