diff --git a/docs/DeveloperPolicy.html b/docs/DeveloperPolicy.html new file mode 100644 index 00000000000..9b971759cb9 --- /dev/null +++ b/docs/DeveloperPolicy.html @@ -0,0 +1,436 @@ + + + + LLVM Developer Policy + + + +
DRAFT Only.
+ +
LLVM Developer Policy
+
+

Contents

+
    +
  1. Overview
    2. +
  2. Terminology
    3. +
  3. Copyright and License +
      +
    1. Copyright
      2. +
    2. License
      3. +
    3. Developer Agreements
      4. +
    4. +
  4. General Policies +
      +
    1. Stay Informed
      2. +
    2. Starting New Work
      3. +
    3. Code Reviews
      4. +
    4. Incremental Development
      5. +
    5. Quality
      6. +
    6. Test Cases
      7. +
    5. +
  5. Patch Policies +
      +
    1. Patch Form
      2. +
    2. Patch Testing
      3. +
    3. Patch Submission
      4. +
    4. After Submission
      5. +
    5. Obtaining Commit Access
      6. +
    6. New Committers
      7. +
    6. +
+
Written by LLVM Oversight Team
+		 + + +
Overview
+ +
+

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.

+
+ +
Terminology
+ +
+

So that the policies defined in the next sections are clear, we first + define some terms here.

+
+
Change
+
Any modification to LLVM including documentation, tests, build system, + etc. either in patch or + commit form.
+
Commit
+
A change submitted directly to LLVM software + respository via the cvs commit command.
+
Developer
+
Anyone who submits a change to LLVM.
+
Increment
+
A change or set of changes, whether by + patch or commit, that are + related by a single common purpose. Increments are atomic as they + leave LLVM in a stable state (both compiling and working properly).
+
Must
+
When used in a policy statement, the term must implies a + non-optional requirement on the developer.
+
Patch
+
A change submitted by email in patch (diff) + format generated by the cvs diff command.
+
Should
+
When used in a policy statement, the term should implies a + recommended but optional requirement on the developer.
+
+
+ +
+ + +
Copyright and License
+ +
+

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).

+
+ +
Copyright
+
+

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.

+

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. +

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.

+
+ +
License
+
+

LLVM licensing decisions will be made by the LLVM Oversight Group. Any + issues, comments or suggestions with the licensing should be sent to + oversight@llvm.org.

+

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:

+ +

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.

+
+ +
Developer Agreements
+
+

With regards to the LLVM copyright and licensing, developer's agree to:

+ +
+ + +
General 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

+

+ + +
Stay Informed
+
+

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 highly suggested that you + also subscribe to the llvm-commits list and pay attention to changes being + made by others.

+

Active developers must register an email account with bugzilla + (http://llvm.org/bugs/) and preferably + subscribe to the llvm-bugs email list to keep track of bugs occuring in + LLVM.

+
+ + +
Starting New Work
+
+

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: +

+
+ + +
Code Reviews
+
+

LLVM has a code review policy. Code review is an excellent way to ensure + high quality in the software. The following policies apply:

+
    +
  1. All developers are required to have any significant changes reviewed + before they are committed to the repository.
    2. +
  2. Code reviews are conducted by email.
    3. +
  3. Code can be reviewed either before it is committed or after.
    4. +
  4. The developer responsible for a code change is also responsible for + making all necessary review changes.
    5. +
  5. 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.
    6. +
+
+ + +
Incremental Development +
+
+

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:

+
    +
  1. 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.
    2. +
  2. An increment is the smallest patch size necessary to effect one change + in LLVM.
    3. +
  3. Increments can be stand alone (e.g. to fix a bug), or part of a planned + series of increments towards some development goal.
    4. +
  4. 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.
    5. +
+
+ + +
Quality
+
+

The minimum quality standards for any change to the main development + branch are:

+
    +
  1. Code must adhere to the + LLVM Coding Standards.
    2. +
  2. Code must compile cleanly (no errors, no warnings) on at least one + platform.
    3. +
  3. Code must pass the deja gnu (llvm/test) test suite.
    4. +
  4. +
+

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 before the code is submitted for review or committed.

+
    +
  1. Code must compile cleanly on all platforms.
    2. +
  2. Code must pass the llvm-test test suite including + SPEC CINT2000, SPEC CFP2000, SPEC CINT2006, and SPEC CFP2006.
    3. +
  3. The changesat must not cause performance or correctness regressions + for the LLVM tools.
    4. +
  4. The changes must not cause performance or correctness regressions in + code compiled with LLVM on all applicable targets.
    5. +
+
+ + +
Test Cases
+
+

Developers are required to create test cases for regressions and new + features and include them with their changes. The following policies + apply:

+
    +
  1. All feature and regression test cases must be added to the + llvm/test directory. The appropriate subdirectory should be + selected (see the Testing Guide for + details.
    2. +
  2. Test cases should be written in LLVM assembly language unless the + feature or regression being tested requires another language.
    3. +
  3. Test cases, especially for regressions, should be as reduced as + possible, preferably by + bugpoint. It is unacceptable + to place an entire failing program into llvm/test as this creates + a time-to-test burden on all developers. Keep them short!
    4. +
  4. More extensive test cases (applications, benchmarks, etc.) should be + added to the llvm-test test suite, after approval from the + Oversight Group. This test suite is for coverage not features or + regressions.
    5. +
+
+ + +
Patch Policies
+ +
+

This section contains policies that pertain to submitting patches + to LLVM and committing code to the repository

+
+ +
Patch Form
+
+

When submitting a patch, developers must follow these rules:

+
    +
  1. Patches must be made against the CVS HEAD (main development trunk), + not a branch.
    2. +
  2. Patches must be made with this cvs command:
    +    cvs diff -Ntdup -5
    or with the utility utils/mkpatch.
    3. +
  3. Patches must not include differences in generated code such as the + code generated by flex, bison or tblgen. The + utils/mkpatch utility takes care of this for you.
    4. +
+
+ +
Patch Testing
+
+

Before a patch is submitted for review, it should be tested to ensure + that:

+
    +
  1. The patch must compile against the CVS HEAD cleanly (zero warnings, zero + errors).
    2. +
  2. All the llvm/test (Deja Gnu) tests must pass.
    3. +
  3. All the llvm-test tests must pass on at least one platform.
    4. +
+
+ +
Patch Submission
+
+

When a patch is ready to be submitted, these policies apply:

+
    +
  1. Patches should be submitted immediately after they are generated. Stale + patches are unlikely to apply correctly and could be rejected simply due to + age.
    2. +
  2. Patches must be submitted by e-mail to the + + llvm-commits list.
    3. +
+
+ + +
After Submission
+
+

After a patch has been submitted, these policies apply:

+
    +
  1. The patch is subject to review by anyone on the llvm-commits email list. +
    2. +
  2. Any changes recommended by the reviewer must be made by the submitter + of the patch and the patch re-submitted.
    3. +
  3. If the submitter believes the review comment is in error, a response to + the + llvm-commits list should be made explaining why the recommendation + cannot be followed.
    4. +
+
+ + +
After Commit
+
+

After a patch has been committed, these policies apply:

+
    +
  1. The patch is subject to further review by anyone on the llvm-commits + email list.
    2. +
  2. The patch submitter is responsible for all aspects of the patch per + the quality policy above.
    3. +
  3. If the patch is discovered to not meet the + quality standards standards within a reasonable time + frame (24 hours), it may be subject to reversal.
    4. +
+
+ + +
Gaining Commit Access
+
+

Commit access to the repository is granted according to this policy:

+
    +
  1. Commit access is not granted to anyone unless they specifically ask for + it.
    2. +
  2. Requests for commit access must be sent to the LLVM Oversight Group at + oversight@llvm.org.
    3. +
  3. Granting commit access is at the sole discretion of the LLVM Oversight + Group.
    4. +
  4. Submitting patches to LLVM via the patch policy above will greatly + increase the chance that your request for commit access is granted.
    5. +
  5. Getting to know the members of the LLVM community (email, IRC, in person + contact, etc.) will also increase your chances.
    6. +
+
+ + +
New Committers
+
+

For those who have recently obtained commit access, the following policies + apply:

+
    +
  1. You are granted commit-after-approval 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.
    2. +
  2. You are granted commit-without-approavl 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.
    3. +
  3. Commits that violate the quality standards 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.
    4. +
  4. 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.
    5. +
+
+ + +
Policy Notes
+ +
+

This section contains some notes on policy topics that need to be + resolved and incorporated into the main body of the document above.

+
    +
  1. 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?
    2. +
+
+ + +
+
+ Valid CSS! + Valid HTML 4.01! + Written By: LLVM Oversight Group
+ The LLVM Compiler Infrastructure
+ Last modified: $Date$ +
+ +