[llvm-commits] CVS: llvm/docs/DeveloperPolicy.html
Reid Spencer
reid at x10sys.com
Tue Feb 13 01:06:18 PST 2007
Changes in directory llvm/docs:
DeveloperPolicy.html added (r1.1)
---
Log message:
First draft of the LLVM Developer Policy. This document is a "first cut"
at stating in clear terms the LLVM project's policies with respect to
developers and their contributions. Feedback on this is welcome while it
is in draft stage.
---
Diffs of the changes: (+436 -0)
DeveloperPolicy.html | 436 +++++++++++++++++++++++++++++++++++++++++++++++++++
1 files changed, 436 insertions(+)
Index: llvm/docs/DeveloperPolicy.html
diff -c /dev/null llvm/docs/DeveloperPolicy.html:1.1
*** /dev/null Tue Feb 13 03:06:11 2007
--- llvm/docs/DeveloperPolicy.html Tue Feb 13 03:06:01 2007
***************
*** 0 ****
--- 1,436 ----
+ <!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.</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="#overview">Overview</a></li>
+ <li><a href="#terms">Terminology</a></li>
+ <li><a href="#candl">Copyright and License</a>
+ <ol>
+ <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="#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_after">After Submission</a></li>
+ <li><a href="#c_access">Obtaining Commit Access</a></li>
+ <li><a href="#c_new">New Committers</a></li>
+ </ol></li>
+ </ol>
+ <div class="doc_author">Written by LLVM Oversight Team</div>
+ </td><td class="layout">
+
+ <!--=========================================================================-->
+ <div class="doc_section"><a name="overview">Overview</a></div>
+ <!--=========================================================================-->
+ <div class="doc_text">
+ <p>This document contains the LLVM Developer Policy which defines the
+ project's policy towards developer's 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>
+ </div>
+ <!--=========================================================================-->
+ <div class="doc_section"><a name="terms">Terminology</a></div>
+ <!--=========================================================================-->
+ <div class="doc_text">
+ <p>So that the policies defined in the next sections are clear, we first
+ 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
+ respository via the <tt>cvs commit</tt> command.</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>
+
+ </td></tr></table>
+
+ <!--=========================================================================-->
+ <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.
+ A copyright is literally the "right to copy". It is a set of exclusive rights
+ granted to a party regulating the particular expression of information.
+ In this case, the information is LLVM. A license is something granted by a
+ copyright holder to other parties that controls the use of the information
+ by them. 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 Open Source License (see LICENSE.txt).</p>
+ </div>
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"><a name="copyright">Copyright</a></div>
+ <div class="doc_text">
+ <p>The LLVM project believes in correct attribution of contributions to
+ their contributors. Developers should, therefore, place their name at the
+ top of any source file they originate and list their contributions in the
+ CREDITS.TXT file. Furthermore, correct attribution of submitted patches
+ should be made in the commit comments.</p>
+ <p>However, 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
+ <a href="mailto:oversight at llvm.org">oversight at llvm.org</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
+ University of Illinois Open Source License (see LICENSE.TXT), which boils
+ down to this:</p>
+ <ul>
+ <li>You can freely distribute LLVM.</li>
+ <li>You must retain the copyright notice if you redistribute.</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. The
+ intent of the license is to let people use LLVM freely with only the
+ obligation to be honest about where it came from.</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, developer's agree to:</p>
+ <ul>
+ <li>give up their copy rights to 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 or subsequent license chosen by the LLVM Oversight Group.</li>
+ <li>not make LLVM available under any other licensing agreement.</li>
+ </ul>
+ </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.
+ <p>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="mailto:llvmdev at llvm.org">llvmdev</a> email list. If you are doing
+ anything more than just casual work on LLVM, it is highly suggested that you
+ also subscribe to the llvm-commits list and pay attention to changes being
+ made by others.</p>
+ <p>Active developers must register an email account with bugzilla
+ (<a href="http://llvm.org/bugs/">http://llvm.org/bugs/</a>) and preferably
+ subscribe to the llvm-bugs email list to keep track of bugs occuring 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 new work with the aim of contributing it back to
+ LLVM, s/he must inform the community with an email to llvm-dev 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 issues around the proposed work are discussed and
+ resolved before any significant work is accomplished.</li>
+ </ul>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <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 any 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>
+ </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>
+ <li>
+ </ol>
+ <p>Additionally, the committer is responsible for all of the following items.
+ It is considered significantly preferable for all of these items to be
+ accounted for <i>before</i> the code is submitted for review or committed.</p>
+ <ol>
+ <li>Code must compile cleanly on all platforms.</li>
+ <li>Code must pass the <tt>llvm-test</tt> test suite including
+ SPEC CINT2000, SPEC CFP2000, SPEC CINT2006, and SPEC CFP2006.</li>
+ <li>The changesat must not cause performance or correctness regressions
+ for the LLVM tools.</li>
+ <li>The changes must not cause performance or correctness regressions in
+ code compiled with 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 subdirectory should be
+ selected (see the <a href="TestingGuide.html">Testing Guide</a> for
+ details.</li>
+ <li>Test cases should be written in LLVM assembly language unless the
+ feature or regression being tested requires another language.</li>
+ <li>Test cases, especially for regressions, should be as reduced as
+ possible, preferably by
+ <a href=CommandGuide/html/bugpoint.html>bugpoint</a>. 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. Keep them short!</li>
+ <li>More extensive test cases (applications, benchmarks, etc.) should be
+ added to the <tt>llvm-test</tt> test suite, after approval from the
+ Oversight Group. 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 must be made with this cvs command:<pre>
+ cvs diff -Ntdup -5</pre> or with the utility <tt>utils/mkpatch</tt>.</li>
+ <li>Patches must 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>
+ </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>All the llvm-test tests must pass on at least one platform.</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 are unlikely to apply correctly and could be rejected simply due to
+ age.</li>
+ <li>Patches must 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_after">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 llvm-commits email list.
+ </li>
+ <li>Any changes recommended by the reviewer must be made by the submitter
+ of the patch and the patch re-submitted.</li>
+ <li>If the submitter believes the review comment is in error, a response to
+ the <a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits">
+ llvm-commits</a> list should be made explaining why the recommendation
+ cannot be followed.</li>
+ </ol>
+ </div>
+
+ <!-- _______________________________________________________________________ -->
+ <div class="doc_subsection"> <a name="p_after">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 standards</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">Gaining 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 LLVM Oversight Group at
+ <a href="mailto:oversight at llvm.org">oversight at llvm.org</a>.</li>
+ <li>Granting commit access is at the sole discretion of the LLVM Oversight
+ Group.</li>
+ <li>Submitting patches to LLVM via the patch policy above will greatly
+ increase the chance that your request for commit access is granted.</li>
+ <li>Getting to know the members of the LLVM community (email, IRC, in person
+ contact, etc.) will also increase your chances.</li>
+ </ol>
+ </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 llvm-commits per the patch policies
+ above. When approved you may commit it yourself.</li>
+ <li>You are granted <i>commit-without-approavl</i> 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 developers is welcome to re-commit the change after
+ the problem has been fixed.</li>
+ <li>Multiple violations of these policies or a single aggregious violation
+ may cause commit access to be revoked, at the sole discretion of the
+ LLVM Oversight Group.</li>
+ </ol>
+ </div>
+
+ <!--=========================================================================-->
+ <div class="doc_section"><a name="notes">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: <a href="mailto:oversight at llvm.org">LLVM Oversight Group</a><br>
+ <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date: 2007/02/13 09:06:01 $
+ </address>
+ </body>
+ </html>
More information about the llvm-commits
mailing list