This document contains the LLVM Developer Policy which defines the project's - policy towards developers and their contributions. The intent of this policy - is to eliminate miscommunication, rework, and confusion that might arise from - the distributed nature of LLVM's development. By stating the policy in clear - terms, we hope each developer can know ahead of time what to expect when - making LLVM contributions. This policy covers all llvm.org subprojects, - including Clang, LLDB, libc++, etc.
-This policy is also designed to accomplish the following objectives:
- -This policy is aimed at frequent contributors to LLVM. People interested in - contributing one-off patches can do so in an informal way by sending them to - the - llvm-commits - mailing list and engaging another developer to see it through the - process.
-This section contains policies that pertain to frequent LLVM developers. We - always welcome one-off patches from people who do not - routinely contribute to LLVM, but we expect more from frequent contributors - to keep the system as efficient as possible for everyone. Frequent LLVM - contributors are expected to meet the following requirements in order for - LLVM to maintain a high standard of quality.
- - -
Developers should stay informed by reading at least the "dev" mailing list - for the projects you are interested in, such as - llvmdev for - LLVM, cfe-dev - for Clang, or lldb-dev - for LLDB. If you are doing anything more than just casual work on LLVM, it - is suggested that you also subscribe to the "commits" mailing list for the - subproject you're interested in, such as - llvm-commits, - cfe-commits, - or lldb-commits. - Reading the "commits" list and paying attention to changes being made by - others is a good way to see what other people are interested in and watching - the flow of the project as a whole.
- -We recommend that active developers register an email account with - LLVM Bugzilla and preferably subscribe to - the llvm-bugs - email list to keep track of bugs and enhancements occurring in LLVM. We - really appreciate people who are proactive at catching incoming bugs in their - components and dealing with them promptly.
-When making a patch for review, the goal is to make it as easy for the - reviewer to read it as possible. As such, we recommend that you:
- -When sending a patch to a mailing list, it is a good idea to send it as an - attachment to the message, not embedded into the text of the - message. This ensures that your mailer will not mangle the patch when it - sends it (e.g. by making whitespace changes or by wrapping lines).
- -For Thunderbird users: Before submitting a patch, please open - Preferences → Advanced → General → Config Editor, - find the key mail.content_disposition_type, and set its value to - 1. Without this setting, Thunderbird sends your attachment using - Content-Disposition: inline rather than Content-Disposition: - attachment. Apple Mail gamely displays such a file inline, making it - difficult to work with for reviewers using that program.
-LLVM has a code review policy. Code review is one way to increase the quality - of software. We generally follow these policies:
- -Developers should participate in code reviews as both reviewers and - reviewees. If someone is kind enough to review your code, you should return - the favor for someone else. Note that anyone is welcome to review and give - feedback on a patch, but only people with Subversion write access can approve - it.
-The LLVM Project relies on two features of its process to maintain rapid - development in addition to the high quality of its source base: the - combination of code review plus post-commit review for trusted maintainers. - Having both is a great way for the project to take advantage of the fact that - most people do the right thing most of the time, and only commit patches - without pre-commit review when they are confident they are right.
- -The trick to this is that the project has to guarantee that all patches that - are committed are reviewed after they go in: you don't want everyone to - assume someone else will review it, allowing the patch to go unreviewed. To - solve this problem, we have a notion of an 'owner' for a piece of the code. - The sole responsibility of a code owner is to ensure that a commit to their - area of the code is appropriately reviewed, either by themself or by someone - else. The current code owners are:
- -Note that code ownership is completely different than reviewers: anyone can - review a piece of code, and we welcome code review from anyone who is - interested. Code owners are the "last line of defense" to guarantee that all - patches that are committed are actually reviewed.
- -Being a code owner is a somewhat unglamorous position, but it is incredibly - important for the ongoing success of the project. Because people get busy, - interests change, and unexpected things happen, code ownership is purely - opt-in, and anyone can choose to resign their "title" at any time. For now, - we do not have an official policy on how one gets elected to be a code - owner.
-Developers are required to create test cases for any bugs fixed and any new - features added. Some tips for getting your testcase approved:
- -Note that llvm/test and clang/test are designed for regression and small - feature tests only. More extensive test cases (e.g., entire applications, - benchmarks, etc) - should be added to the llvm-test test suite. The llvm-test suite is - for coverage (correctness, performance, etc) testing, not feature or - regression testing.
-The minimum quality standards that any change must satisfy before being - committed to the main development branch are:
- -Additionally, the committer is responsible for addressing any problems found - in the future that the change is responsible for. For example:
- -We prefer for this to be handled before submission but understand that it - isn't possible to test all of this for every submission. Our build bots and - nightly testing infrastructure normally finds these problems. A good rule of - thumb is to check the nightly testers for regressions the day after your - change. Build bots will directly email you if a group of commits that - included yours caused a failure. You are expected to check the build bot - messages to see if they are your fault and, if so, fix the breakage.
- -Commits that violate these quality standards (e.g. are very broken) may be - reverted. This is necessary when the change blocks other developers from - making progress. The developer is welcome to re-commit the change after the - problem has been fixed.
-We grant commit access to contributors with a track record of submitting high - quality patches. If you would like commit access, please send an email to - Chris with the following - information:
- -Once you've been granted commit access, you should be able to check out an - LLVM tree with an SVN URL of "https://username@llvm.org/..." instead of the - normal anonymous URL of "http://llvm.org/...". The first time you commit - you'll have to type in your password. Note that you may get a warning from - SVN about an untrusted key, you can ignore this. To verify that your commit - access works, please do a test commit (e.g. change a comment or add a blank - line). Your first commit to a repository may require the autogenerated email - to be approved by a mailing list. This is normal, and will be done when - the mailing list owner has time.
- -If you have recently been granted commit access, these policies apply:
- -In any case, your changes are still subject to code - review (either before or after they are committed, depending on the - nature of the change). You are encouraged to review other peoples' patches - as well, but you aren't required to.
-When a developer begins a major new project with the aim of contributing it - back to LLVM, s/he should inform the community with an email to - the llvmdev - email list, to the extent possible. The reason for this is to: - -
The design of LLVM is carefully controlled to ensure that all the pieces fit - together well and are as consistent as possible. If you plan to make a major - change to the way LLVM works or want to add a major new extension, it is a - good idea to get consensus with the development community before you start - working on it.
- -Once the design of the new feature is finalized, the work itself should be - done as a series of incremental changes, not as a - long-term development branch.
-In the LLVM project, we do all significant changes as a series of incremental - patches. We have a strong dislike for huge changes or long-term development - branches. Long-term development branches have a number of drawbacks:
- -To address these problems, LLVM uses an incremental development style and we - require contributors to follow this practice when making a large/invasive - change. Some tips:
- -If you are interested in making a large change, and this scares you, please - make sure to first discuss the change/gather consensus - then ask about the best way to go about making the change.
-We believe in correct attribution of contributions to their contributors. - However, we do not want the source code to be littered with random - attributions "this code written by J. Random Hacker" (this is noisy and - distracting). In practice, the revision control system keeps a perfect - history of who changed what, and the CREDITS.txt file describes higher-level - contributions. If you commit a patch for someone else, please say "patch - contributed by J. Random Hacker!" in the commit message.
- -Overall, please do not add contributor names to the source code.
-NOTE: This section deals with - legal matters but does not provide legal advice. We are not lawyers — - please seek legal counsel from an attorney.
-This section addresses the issues of copyright, license and patents for the - LLVM project. The copyright for the code is held by the individual - contributors of the code and the terms of its license to LLVM users and - developers is the - University of - Illinois/NCSA Open Source License (with portions dual licensed under the - MIT License, - see below). As contributor to the LLVM project, you agree to allow any - contributions to the project to licensed under these terms.
- - - -The LLVM project does not require copyright assignments, which means that the - copyright for the code in the project is held by its respective contributors - who have each agreed to release their contributed code under the terms of the - LLVM License.
- -An implication of this is that the LLVM license is unlikely to ever change: - changing it would require tracking down all the contributors to LLVM and - getting them to agree that a license change is acceptable for their - contribution. Since there are no plans to change the license, this is not a - cause for concern.
- -As a contributor to the project, this means that you (or your company) retain - ownership of the code you contribute, that it cannot be used in a way that - contradicts the license (which is a liberal BSD-style license), and that the - license for your contributions won't change without your approval in the - future.
- -We intend to keep LLVM perpetually open source and to use a liberal open - source license. As a contributor to the project, you agree that any - contributions be licensed under the terms of the corresponding - subproject. - All of the code in LLVM is available under the - University of - Illinois/NCSA Open Source License, which boils down to this:
- -We believe this fosters the widest adoption of LLVM because it allows - commercial products to be derived from LLVM with few restrictions and - without a requirement for making any derived works also open source (i.e. - LLVM's license is not a "copyleft" license like the GPL). We suggest that you - read the License - if further clarification is needed.
- -In addition to the UIUC license, the runtime library components of LLVM - (compiler_rt, libc++, and libclc) are also licensed under the MIT license, - which does not contain the binary redistribution clause. As a user of these - runtime libraries, it means that you can choose to use the code under either - license (and thus don't need the binary redistribution clause), and as a - contributor to the code that you agree that any contributions to these - libraries be licensed under both licenses. We feel that this is important - for runtime libraries, because they are implicitly linked into applications - and therefore should not subject those applications to the binary - redistribution clause. This also means that it is ok to move code from (e.g.) - libc++ to the LLVM core without concern, but that code cannot be moved from - the LLVM core to libc++ without the copyright owner's permission. -
- -Note that the LLVM Project does distribute llvm-gcc and dragonegg, which - are GPL. - This means that anything "linked" into llvm-gcc must itself be compatible - with the GPL, and must be releasable under the terms of the GPL. This - implies that any code linked into llvm-gcc and distributed to others may - be subject to the viral aspects of the GPL (for example, a proprietary - code generator linked into llvm-gcc must be made available under the GPL). - This is not a problem for code already distributed under a more liberal - license (like the UIUC license), and GPL-containing subprojects are kept - in separate SVN repositories whose LICENSE.txt files specifically indicate - that they contain GPL code.
- -We have no plans to change the license of LLVM. If you have questions or - comments about the license, please contact the - LLVM Developer's Mailing List.
-To the best of our knowledge, LLVM does not infringe on any patents (we have - actually removed code from LLVM in the past that was found to infringe). - Having code in LLVM that infringes on patents would violate an important goal - of the project by making it hard or impossible to reuse the code for - arbitrary purposes (including commercial use).
- -When contributing code, we expect contributors to notify us of any potential - for patent-related trouble with their changes (including from third parties). - If you or your employer own - the rights to a patent and would like to contribute code to LLVM that relies - on it, we require that the copyright owner sign an agreement that allows any - other user of LLVM to freely use your patent. Please contact - the oversight group for more - details.
-
-