| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" |
| "http://www.w3.org/TR/html4/strict.dtd"> |
| <html> |
| <head> |
| <title>LLVM Developer Policy</title> |
| <link rel="stylesheet" href="llvm.css" type="text/css"> |
| </head> |
| <body> |
| <div class="doc_warning">DRAFT Only. DRAFT Only. DRAFT Only. DRAFT Only.</div> |
| |
| <div class="doc_title">LLVM Developer Policy</div> |
| <table class="layout"><tr class="layout"><td class="layout"> |
| <h2>Contents</h2> |
| <ol> |
| <li><a href="#introduction">Introduction</a></li> |
| <li><a href="#general">General Policies</a> |
| <ol> |
| <li><a href="#informed">Stay Informed</a> </li> |
| <li><a href="#newwork">Starting New Work</a></li> |
| <li><a href="#reviews">Code Reviews</a></li> |
| <li><a href="#incremental">Incremental Development</a></li> |
| <li><a href="#quality">Quality</a></li> |
| <li><a href="#testcases">Test Cases</a></li> |
| </ol></li> |
| <li><a href="#patches">Patch Policies</a> |
| <ol> |
| <li><a href="#p_form">Patch Form</a></li> |
| <li><a href="#p_testing">Patch Testing</a></li> |
| <li><a href="#p_submission">Patch Submission</a></li> |
| <li><a href="#p_aftersub">After Submission</a></li> |
| <li><a href="#p_aftercommit">After Commit</a></li> |
| <li><a href="#c_access">Obtaining Commit Access</a></li> |
| <li><a href="#c_new">New Committers</a></li> |
| </ol></li> |
| <li><a href="#candl">Copyright and License</a> |
| <ol> |
| <li><a href="#attribution">Attribution</a></li> |
| <li><a href="#copyright">Copyright</a></li> |
| <li><a href="#license">License</a></li> |
| <li><a href="#devagree">Developer Agreements</a></li> |
| </ol></li> |
| <li><a href="#terms">Terminology</a></li> |
| <li><a href="#polnotes">Policy Notes</a></li> |
| </ol> |
| <div class="doc_author">Written by LLVM Oversight Team</div> |
| </td><td class="layout"> |
| |
| <!--=========================================================================--> |
| <div class="doc_section"><a name="introduction">Introduction</a></div> |
| <!--=========================================================================--> |
| <div class="doc_text"> |
| <p>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.</p> |
| <p>This policy is also designed to accomplish the following objectives:</p> |
| <ol> |
| <li>Attract both users and developers to the LLVM project.</li> |
| <li>Make life as simple and easy for contributors as possible.</li> |
| <li>Indicate that LLVM is a mature project with a thriving community and |
| sensible policies directing its ongoing development.</li> |
| </ol> |
| </div> |
| |
| <!--=========================================================================--> |
| <div class="doc_section"><a name="general">General Policies</a></div> |
| <!--=========================================================================--> |
| <div class="doc_text"> |
| <p>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.<p> |
| </div> |
| |
| <!-- _______________________________________________________________________ --> |
| <div class="doc_subsection"> <a name="informed">Stay Informed</a> </div> |
| <div class="doc_text"> |
| <p>Developers should stay informed by reading at least the |
| <a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev">llvmdev</a> |
| email list. If you are doing anything more than just casual work on LLVM, |
| it is suggested that you also subscribe to the |
| <a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits">llvm-commits</a> |
| list and pay attention to changes being made by others.</p> |
| <p>We recommend that active developers register an email account with |
| <a href="http://llvm.org/bugs/">LLVM Bugzilla</a> and preferably subscribe to |
| the <a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmbugs">llvm-bugs</a> |
| email list to keep track of bugs and enhancements occurring in LLVM.</p> |
| </div> |
| |
| <!-- _______________________________________________________________________ --> |
| <div class="doc_subsection"> <a name="newwork">Starting New Work</a></div> |
| <div class="doc_text"> |
| <p>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 <a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev">llvm-dev</a> |
| email list, to the extent possible. The reason for this is to: |
| <ul> |
| <li>keep the community informed about future changes to LLVM, </li> |
| <li>avoid duplication of effort by having multiple parties working on the |
| same thing and not knowing about it, and</li> |
| <li>ensure that any technical issues around the proposed work are |
| discussed and resolved before any significant work is done.</li> |
| </ul> |
| <p>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.</p> |
| </div> |
| </td></tr></table> |
| |
| <!-- _______________________________________________________________________ --> |
| <div class="doc_subsection"> <a name="reviews">Code Reviews</a></div> |
| <div class="doc_text"> |
| <p>LLVM has a code review policy. Code review is an excellent way to ensure |
| high quality in the software. The following policies apply:</p> |
| <ol> |
| <li>All developers are required to have significant changes reviewed |
| before they are committed to the repository.</li> |
| <li>Code reviews are conducted by email.</li> |
| <li>Code can be reviewed either before it is committed or after.</li> |
| <li>The developer responsible for a code change is also responsible for |
| making all necessary review changes.</li> |
| <li>Developers should participate in code reviews as both a reviewer and |
| a reviewee. We don't have a dedicated team of reviewers. If someone is |
| kind enough to review your code, you should return the favor for someone |
| else.</li> |
| </ol> |
| </div> |
| |
| <!-- _______________________________________________________________________ --> |
| <div class="doc_subsection"> <a name="incremental">Incremental Development</a> |
| </div> |
| <div class="doc_text"> |
| <p>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:</p> |
| <ol> |
| <li>The first task is to define the increment and get consensus (with the |
| LLVM development community) on what the end goal of the change is. Making |
| random small changes that go nowhere is not useful for anyone.</li> |
| <li>An increment is the smallest patch size necessary to effect one change |
| in LLVM.</li> |
| <li>Increments can be stand alone (e.g. to fix a bug), or part of a planned |
| series of increments towards some development goal.</li> |
| <li>Increments should be kept as small as possible. This simplifies your |
| work (into a logical progression), simplifies code review and reduces the |
| chance that you will get negative feedback on the change. Small increments |
| also facilitate the maintenance of a high quality code base.</li> |
| <li>Larger increments require a larger testing effort.</li> |
| </ol> |
| </div> |
| |
| <!-- _______________________________________________________________________ --> |
| <div class="doc_subsection"> <a name="quality">Quality</a></div> |
| <div class="doc_text"> |
| <p>The minimum quality standards for any change to the main development |
| branch are:</p> |
| <ol> |
| <li>Code must adhere to the |
| <a href="CodingStandards.html">LLVM Coding Standards</a>.</li> |
| <li>Code must compile cleanly (no errors, no warnings) on at least one |
| platform.</li> |
| <li>Code must pass the deja gnu (llvm/test) test suite.</li> |
| </ol> |
| <p>Additionally, the committer is responsible for addressing all of the |
| following items (preferably before submission):</p> |
| <ol> |
| <li>The code should compile cleanly on all platforms.</li> |
| <li>The changes should not cause regressions in the <tt>llvm-test</tt> |
| suite including SPEC CINT2000, SPEC CFP2000, SPEC CINT2006, and |
| SPEC CFP2006.</li> |
| <li>The change set should not cause performance or correctness regressions |
| for the LLVM tools.</li> |
| <li>The changes should not cause performance or correctness regressions in |
| code compiled by LLVM on all applicable targets.</li> |
| </ol> |
| </div> |
| |
| <!-- _______________________________________________________________________ --> |
| <div class="doc_subsection"> <a name="testcases">Test Cases</a></div> |
| <div class="doc_text"> |
| <p>Developers are required to create test cases for regressions and new |
| features and include them with their changes. The following policies |
| apply:</p> |
| <ol> |
| <li>All feature and regression test cases must be added to the |
| <tt>llvm/test</tt> directory. The appropriate sub-directory should be |
| selected (see the <a href="TestingGuide.html">Testing Guide</a> for |
| details).</li> |
| <li>Test cases should be written in |
| <a href="LangRef.html">LLVM assembly language</a> unless the |
| feature or regression being tested requires another language (e.g. the |
| bug being fixed or feature being implemented is in the lvm-gcc C++ |
| front-end).</li> |
| <li>Test cases, especially for regressions, should be reduced as much as |
| possible, by <a href="CommandGuide/html/bugpoint.html">bugpoint</a> or |
| manually. It is unacceptable |
| to place an entire failing program into <tt>llvm/test</tt> as this creates |
| a <i>time-to-test</i> burden on all developers. Please keep them short.</li> |
| <li>More extensive test cases (applications, benchmarks, etc.) should be |
| added to the <tt>llvm-test</tt> test suite. This test suite is for |
| coverage not features or regressions.</li> |
| </ol> |
| </div> |
| |
| <!--=========================================================================--> |
| <div class="doc_section"><a name="patches">Patch Policies</a></div> |
| <!--=========================================================================--> |
| <div class="doc_text"> |
| <p>This section contains policies that pertain to submitting patches |
| to LLVM and committing code to the repository</p> |
| </div> |
| <!-- _______________________________________________________________________ --> |
| <div class="doc_subsection"> <a name="p_form">Patch Form</a></div> |
| <div class="doc_text"> |
| <p>When submitting a patch, developers must follow these rules:</p> |
| <ol> |
| <li>Patches must be made against the CVS HEAD (main development trunk), |
| not a branch.</li> |
| <li>Patches should be made with this command:<pre> |
| cvs diff -Ntdup -5</pre> or with the utility <tt>utils/mkpatch</tt>.</li> |
| <li>Patches should not include differences in generated code such as the |
| code generated by <tt>flex</tt>, <tt>bison</tt> or <tt>tblgen</tt>. The |
| <tt>utils/mkpatch</tt> utility takes care of this for you.</li> |
| <li>Patches must not include any patent violations. To the best of our |
| knowledge, LLVM is free of any existing patent violations and it is our |
| intent to keep it that way. </li> |
| </ol> |
| </div> |
| <!-- _______________________________________________________________________ --> |
| <div class="doc_subsection"> <a name="p_testing">Patch Testing</a></div> |
| <div class="doc_text"> |
| <p>Before a patch is submitted for review, it should be tested to ensure |
| that:</p> |
| <ol> |
| <li>The patch must compile against the CVS HEAD cleanly (zero warnings, zero |
| errors).</li> |
| <li>All the llvm/test (Deja Gnu) tests must pass.</li> |
| <li>The patch should cause no regressions in the llvm-test test suite. How |
| much testing is appropriate depends on the nature of the patch. We leave it |
| to your good judgement, but you will be responsible for fixing any |
| regressions or reverting the patch.</li> |
| </ol> |
| </div> |
| <!-- _______________________________________________________________________ --> |
| <div class="doc_subsection"> <a name="p_submission">Patch Submission</a></div> |
| <div class="doc_text"> |
| <p>When a patch is ready to be submitted, these policies apply:</p> |
| <ol> |
| <li>Patches should be submitted immediately after they are generated. Stale |
| patches may not apply correctly if the underlying code changes between the |
| time the patch was created and the time it is applied.</li> |
| <li>Patches should be submitted by e-mail to the |
| <a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits"> |
| llvm-commits</a> list.</li> |
| </ol> |
| </div> |
| |
| <!-- _______________________________________________________________________ --> |
| <div class="doc_subsection"> <a name="p_aftersub">After Submission</a></div> |
| <div class="doc_text"> |
| <p>After a patch has been submitted, these policies apply:</p> |
| <ol> |
| <li>The patch is subject to review by anyone on the |
| <a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits">llvm-commits</a> |
| email list.</li> |
| <li>Changes recommended by a reviewer should be incorporated into your |
| patch or you should explain why the reviewer is incorrect. |
| <li>Changes to the patch must be re-submitted to the |
| <a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits">llvm-commits</a> |
| email list.</li> |
| <li>This process iterates until all review issues have been addressed.</li> |
| </ol> |
| </div> |
| |
| <!-- _______________________________________________________________________ --> |
| <div class="doc_subsection"> <a name="p_aftercommit">After Commit</a></div> |
| <div class="doc_text"> |
| <p>After a patch has been committed, these policies apply:</p> |
| <ol> |
| <li>The patch is subject to further review by anyone on the llvm-commits |
| email list.</li> |
| <li>The patch submitter is responsible for all aspects of the patch per |
| the <a href="quality">quality policy</a> above.</li> |
| <li>If the patch is discovered to not meet the |
| <a href="quality">quality policy</a> standards within a reasonable time |
| frame (24 hours), it may be subject to reversal.</li> |
| </ol> |
| </div> |
| |
| <!-- _______________________________________________________________________ --> |
| <div class="doc_subsection"> <a name="c_access">Obtaining Commit Access</a></div> |
| <div class="doc_text"> |
| <p>Commit access to the repository is granted according to this policy:</p> |
| <ol> |
| <li>Commit access is not granted to anyone unless they specifically ask for |
| it.</li> |
| <li>Requests for commit access must be sent to the |
| <a href="mailto:llvm-oversight@cs.uiuc.edu">LLVM Oversight Group</a>.</li> |
| <li>Granting commit access is at the sole discretion of the LLVM Oversight |
| Group.</li> |
| </ol> |
| <p>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.</p> |
| </div> |
| |
| <!-- _______________________________________________________________________ --> |
| <div class="doc_subsection"> <a name="c_new">New Committers</a></div> |
| <div class="doc_text"> |
| <p>For those who have recently obtained commit access, the following policies |
| apply:</p> |
| <ol> |
| <li>You are granted <i>commit-after-approval</i> to all parts of LLVM. |
| To get approval, submit a patch to |
| <a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits">llvm-commits</a> |
| per the <a href="#patches">patch policies</a> above. When approved you |
| may commit it yourself.</li> |
| <li>You are allowed to commit patches without approval which you think are |
| obvious. This is clearly a subjective decision. We simply expect you to |
| use good judgement.</li> |
| <li>You are allowed to commit patches without approval to those portions |
| of LLVM that you own (contributed) or maintain (have been assigned |
| responsibility for), with the proviso that such commits must not break the |
| build. This is a "trust but verify" policy and commits of this nature are |
| reviewed after they are committed.</li> |
| <li>Commits that violate the <a href="quality">quality standards</a> 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.</li> |
| <li>Multiple violations of these policies or a single egregious violation |
| may cause commit access to be revoked.</li> |
| </ol> |
| </div> |
| |
| <!--=========================================================================--> |
| <div class="doc_section"><a name="candl">Copyright and License</a></div> |
| <!--=========================================================================--> |
| <div class="doc_text"> |
| <p>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 |
| <a href="http://www.opensource.org/licenses/UoI-NCSA.php">University of |
| Illinois/NCSA Open Source License</a>. |
| </div> |
| |
| <div class="doc_notes"> |
| <p>NOTE: This section deals with legal matters but does not provide legal |
| advice. It is intended only as a general guideline.</p> |
| </div> |
| |
| <!-- _______________________________________________________________________ --> |
| <div class="doc_subsection"><a name="attribution">Attribution</a></div> |
| <div class="doc_text"> |
| <p>The LLVM project believes in correct attribution of contributions to |
| their contributors, as follows:</p> |
| <ol> |
| <li>Developers who originate new files in LLVM should place their name at |
| the top of the file per the |
| <a href="CodingStandards.html">Coding Standards</a>.</li> |
| <li>There should be only one name at the top of the file and it should be |
| the person who created the file.</li> |
| <li>Placing your name in the file does not imply copyright but does |
| correctly attribute the file to its author.</li> |
| <li>Developers should be aware that after some time has passed, the name at |
| the top of a file may become meaningless as maintenance/ownership of files |
| changes.</li> |
| <li>Developers should submit or commit patches to the |
| <a href="http://llvm.org/cvsweb/cvsweb.cgi/llvm/CREDITS.TXT?rev=1.67&content-type=text/x-cvsweb-markup">CREDITS.txt</a> |
| file to summarize their contributions.</li> |
| <li>Commit comments should contain correct attribution of the person who |
| submitted the patch if that person is not the committer (i.e. when a |
| developer with commit privileges commits a patch for someone else).</li> |
| </ol> |
| </div> |
| |
| <!-- _______________________________________________________________________ --> |
| <div class="doc_subsection"><a name="copyright">Copyright</a></div> |
| <div class="doc_text"> |
| <p> |
| <p>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. |
| <p>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.</p> |
| </div> |
| <!-- _______________________________________________________________________ --> |
| <div class="doc_subsection"><a name="license">License</a></div> |
| <div class="doc_text"> |
| <p>LLVM licensing decisions will be made by the LLVM Oversight Group. Any |
| issues, comments or suggestions with the licensing should be sent to the |
| <a href="mailto:llvm-oversight@cs.uiuc.edu">LLVM Oversight Group</a>.</p> |
| <p>The LLVM Oversight Group intends to keep LLVM perpetually open source |
| and to use liberal open source licenses. The current license is the |
| <a href="http://www.opensource.org/licenses/UoI-NCSA.php"> |
| University of Illinois/NCSA Open Source License</a>, which boils |
| down to this:</p> |
| <ul> |
| <li>You can freely distribute LLVM.</li> |
| <li>You must retain the copyright notice if you redistribute LLVM.</li> |
| <li>Binaries derived from LLVM must reproduce the copyright notice.</li> |
| <li>You can't use our names to promote your LLVM derived products.</li> |
| <li>There's no warranty on LLVM at all.</li> |
| </ul> |
| <p>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 <i>copyleft</i> license). We suggest that you read |
| the <a href="http://www.opensource.org/licenses/UoI-NCSA.php">License</a> |
| if further clarification is needed.</p> |
| </div> |
| <!-- _______________________________________________________________________ --> |
| <div class="doc_subsection"><a name="devagree">Developer Agreements</a></div> |
| <div class="doc_text"> |
| <p>With regards to the LLVM copyright and licensing, developers agree to:</p> |
| <ul> |
| <li>assign their copy rights to UIUC for any contribution made so that |
| the entire software base can be managed by a single copyright holder.</li> |
| <li>allow their contribution(s) to be licensed as open source by the then |
| current license chosen by the LLVM Oversight Group.</li> |
| </ul> |
| </div> |
| |
| <!--=========================================================================--> |
| <div class="doc_section"><a name="terms">Terminology</a></div> |
| <!--=========================================================================--> |
| <div class="doc_text"> |
| <p>So that the policies defined in this document are clear, we define some |
| terms here.</p> |
| <dl> |
| <dt><a name="t_change">Change</a></dt> |
| <dd>Any modification to LLVM including documentation, tests, build system, |
| etc. either in <a href="#t_patch">patch</a> or |
| <a href="#t_commit">commit</a> form.</dd> |
| <dt><a name="t_commit">Commit</a><dt> |
| <dd>A <a href="t_change">change</a> submitted directly to LLVM software |
| repository via the <tt>cvs commit</tt> command.</dd> |
| <dt><a name="t_copleft">Copyleft</a></dt> |
| <dd>A licensing policy that requires the licensee to adopt the terms of the |
| license for <i>derived</i> works. LLVM does not subscribe to this |
| policy.</dd> |
| <dt><a name="t_developer">Developer</a></dt> |
| <dd>Anyone who submits a <a href="#t_change">change</a> to LLVM.</dd> |
| <dt><a name="t_inrement">Increment</a></dt> |
| <dd>A <a href="#t_change">change</a> or set of changes, whether by |
| <a href="#t_patch">patch</a> or <a href="#t_commit">commit</a>, that are |
| related by a single common purpose. Increments are atomic as they |
| leave LLVM in a stable state (both compiling and working properly).</dd> |
| <dt><a name="t_must">Must</a></dt> |
| <dd>When used in a policy statement, the term <i>must</i> implies a |
| non-optional requirement on the developer.</dd> |
| <dt><a name="t_patch">Patch</a></dt> |
| <dd>A <a href="#t_change">change</a> submitted by email in patch (diff) |
| format generated by the <tt>cvs diff</tt> command.</dd> |
| <dt><a name="t_should">Should</a></dt> |
| <dd>When used in a policy statement, the term <i>should</i> implies a |
| recommended but optional requirement on the developer.</dd> |
| </dl> |
| </div> |
| |
| <!--=========================================================================--> |
| <div class="doc_section"><a name="polnotes">Policy Notes</a></div> |
| <!--=========================================================================--> |
| <div class="doc_text"> |
| <p>This section contains some notes on policy topics that need to be |
| resolved and incorporated into the main body of the document above.</p> |
| <ol> |
| <li>When to open a new bug and when to re-use an existing one. For example |
| PR1158. If the same assertion happens do you open a new bug or reopen |
| 1158?</li> |
| </ol> |
| </div> |
| |
| <!-- *********************************************************************** --> |
| <hr> |
| <address> |
| <a href="http://jigsaw.w3.org/css-validator/check/referer"><img |
| src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a> |
| <a href="http://validator.w3.org/check/referer"><img |
| src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!" /></a> |
| Written By: the |
| <a href="mailto:llvm-oversight@cs.uiuc.edu">LLVM Oversight Group</a><br> |
| <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br> |
| Last modified: $Date$ |
| </address> |
| </body> |
| </html> |