X-Git-Url: http://plrg.eecs.uci.edu/git/?a=blobdiff_plain;f=docs%2FDeveloperPolicy.html;h=52eeeca829e21f2ecfb53510f04f760fbc3ca7bd;hb=b3c4e26dc574fff3697d61c4c6c08df39af4a906;hp=5fab3e79478539857437d257cf9ac21d13f0dd2e;hpb=853418d158ea6ea7f1001b877490e4c79c1da7c2;p=oota-llvm.git diff --git a/docs/DeveloperPolicy.html b/docs/DeveloperPolicy.html index 5fab3e79478..52eeeca829e 100644 --- a/docs/DeveloperPolicy.html +++ b/docs/DeveloperPolicy.html @@ -2,496 +2,618 @@ "http://www.w3.org/TR/html4/strict.dtd">
+
-Contents+LLVM Developer Policy- - |
+
+Introduction-
- 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 mis-communication, 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 is also designed to accomplish the following objectives: -
+
-
+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, 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. Developer Policies-
-
+This section contains policies that pertain generally to LLVM developers. - LLVM Developers are expected to meet the following obligations in order - for LLVM to maintain a high standard of quality. -
+ 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 - llvmdev - email list. If you are doing anything more than just casual work on LLVM, - it is suggested that you also subscribe to the - llvm-commits - list and pay attention to changes being made by others. -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. -Stay Informed+
+ 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. - - -
-
-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 llvm-dev - 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. If you plan to make a major change to the way LLVM works or - a major new extension, it is a good idea to get consensus with the development - community before you start working on it. +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. |
-
LLVM has a code review policy. Code review is an excellent way to ensure - high quality in the software. The following policies apply:
-LLVM uses an incremental development style and all developers are expected - to follow this practice. Incremental development is a big key to LLVM's - success and it is essential that developers submit incremental patches. The - following defines the incremental development approach:
-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.
The minimum quality standards for any change to the main development - branch are:
-Additionally, the committer is responsible for addressing all of the - following items (preferably before submission):
-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.
Developers are required to create test cases for regressions and new - features and include them with their changes. The following policies - apply:
-This section contains policies that pertain to submitting patches - to LLVM and committing code to the repository
+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.
When submitting a patch, developers must follow these rules:
-- cvs diff -Ntdup -5or with the utility utils/mkpatch.
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.
Before a patch is submitted for review, it should be tested to ensure - that:
-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.
When a patch is ready to be submitted, these policies apply:
-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.
After a patch has been submitted, these policies apply:
-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.
After a patch has been committed, these policies apply:
-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.
Commit access to the repository is granted according to this policy:
-Submitting patches to LLVM via the patch policy above will greatly - increase the chance that your request for commit access is granted. Getting - to know the members of the LLVM community (email, IRC, in person contact, - etc.) will also increase your chances.
- +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.
For those who have recently obtained commit access, the following policies - apply:
-We address here the issues of copyright and license for the LLVM project. - The object of the copyright and license is the LLVM source code and - documentation. - Currently, the University of Illinois is the LLVM copyright holder and the - terms of its license to LLVM users and developers is the - University of - Illinois/NCSA Open Source License. -
This section addresses the issues of copyright, license and patents for the + LLVM project. The copyright holder 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.
NOTE: This section deals with legal matters but does not provide legal - advice. It is intended only as a general guideline.
+NOTE: This section deals with + legal matters but does not provide legal advice. We are not lawyers, please + seek legal counsel from an attorney.
The LLVM project believes in correct attribution of contributions to - their contributors, as follows:
--
For consistency and ease of management, the project requires the - copyright for all LLVM software to be held by a single copyright holder. - Although UIUC may assign the copyright of the software to another entity, - the intent for the project is to always have a single entity hold the copy - rights to LLVM at any given time. -
Having multiple copyright holders for various portions of LLVM is - problematic in the management of the software. Having a single copyright - holder is in the best interests of all developers and users as it greatly - reduces the managerial burden for any kind of administrative or technical - decisions about LLVM.
-LLVM licensing decisions will be made by the LLVM Oversight Group. Any - issues, comments or suggestions with the licensing should be sent to the - LLVM Oversight Group.
-The LLVM Oversight Group intends to keep LLVM perpetually open source - and to use liberal open source licenses. The current license is 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). We suggest that you read - the License - if further clarification is needed.
+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.
+With regards to the LLVM copyright and licensing, developers agree to:
-We intend to keep LLVM perpetually open source and to use a liberal open + source license. 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 and libc++) 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, which is 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 does not affect code generated by + llvm-gcc. It may be a problem if you intend to base commercial development + on llvm-gcc without redistributing your source 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.
So that the policies defined in this document are clear, we define some - terms here.
-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. 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.
This section contains some notes on policy topics that need to be - resolved and incorporated into the main body of the document above.
-