X-Git-Url: http://demsky.eecs.uci.edu/git/?a=blobdiff_plain;f=docs%2FDeveloperPolicy.rst;h=508a04fd2d59f9cc7fbf55b33a5a9abad31fed93;hb=12af22e8cc217827cf4f118b0f5e4ebbda9925ae;hp=0f2136aa2edc1a33221d646dbe3e198596da6b5a;hpb=4989188a40c4e9cd1016584960296d795e252a6c;p=oota-llvm.git diff --git a/docs/DeveloperPolicy.rst b/docs/DeveloperPolicy.rst index 0f2136aa2ed..508a04fd2d5 100644 --- a/docs/DeveloperPolicy.rst +++ b/docs/DeveloperPolicy.rst @@ -68,11 +68,14 @@ 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. +Please be aware that all public LLVM mailing lists are public and archived, and +that notices of confidentiality or non-disclosure cannot be respected. + .. _patch: .. _one-off patches: -Making a Patch --------------- +Making and Submitting a Patch +----------------------------- 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: @@ -94,6 +97,12 @@ to read it as possible. As such, we recommend that you: script, please separate out those changes into a separate patch from the rest of your changes. +Once your patch is ready, submit it by emailing it to the appropriate project's +commit mailing list (or commit it directly if applicable). Alternatively, some +patches get sent to the project's development list or component of the LLVM bug +tracker, but the commit list is the primary place for reviews and should +generally be preferred. + 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 @@ -107,6 +116,10 @@ rather than ``Content-Disposition: attachment``. Apple Mail gamely displays such a file inline, making it difficult to work with for reviewers using that program. +When submitting patches, please do not add confidentiality or non-disclosure +notices to the patches themselves. These notices conflict with the `LLVM +License`_ and may result in your contribution being excluded. + .. _code review: Code Reviews @@ -118,7 +131,8 @@ software. We generally follow these policies: #. All developers are required to have significant changes reviewed before they are committed to the repository. -#. Code reviews are conducted by email, usually on the llvm-commits list. +#. Code reviews are conducted by email on the relevant project's commit mailing + list, or alternatively on the project's development list or bug tracker. #. Code can be reviewed either before it is committed or after. We expect major changes to be reviewed before being committed, but smaller changes (or @@ -198,13 +212,10 @@ features added. Some tips for getting your testcase approved: directory. The appropriate sub-directory should be selected (see the :doc:`Testing Guide ` for details). -* Test cases should be written in `LLVM assembly language `_ - unless the feature or regression being tested requires another language - (e.g. the bug being fixed or feature being implemented is in the llvm-gcc C++ - front-end, in which case it must be written in C++). +* Test cases should be written in :doc:`LLVM assembly language `. * Test cases, especially for regressions, should be reduced as much as possible, - by `bugpoint `_ or manually. It is unacceptable to place an + by :doc:`bugpoint ` or manually. It is unacceptable to place an entire failing program into ``llvm/test`` as this creates a *time-to-test* burden on all developers. Please keep them short. @@ -325,7 +336,7 @@ Making a Major Change --------------------- 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 +to LLVM, they should inform the community with an email to the `llvmdev `_ email list, to the extent possible. The reason for this is to: @@ -406,15 +417,47 @@ to go about making the change. Attribution of Changes ---------------------- -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. +When contributors submit a patch to an LLVM project, other developers with +commit access may commit it for the author once appropriate (based on the +progression of code review, etc.). When doing so, it is important to retain +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. + +Also, don't commit patches authored by others unless they have submitted the +patch to the project or you have been authorized to submit them on their behalf +(you work together and your company authorized you to contribute the patches, +etc.). The author should first submit them to the relevant project's commit +list, development list, or LLVM bug tracker component. If someone sends you +a patch privately, encourage them to submit it to the appropriate list first. + + +IR Backwards Compatibility +-------------------------- + +When the IR format has to be changed, keep in mind that we try to maintain some +backwards compatibility. The rules are intended as a balance between convenience +for llvm users and not imposing a big burden on llvm developers: + +* The textual format is not backwards compatible. We don't change it too often, + but there are no specific promises. + +* The bitcode format produced by a X.Y release will be readable by all following + X.Z releases and the (X+1).0 release. + +* Newer releases can ignore features from older releases, but they cannot + miscompile them. For example, if nsw is ever replaced with something else, + dropping it would be a valid way to upgrade the IR. + +* Debug metadata is special in that it is currently dropped during upgrades. -Overall, please do not add contributor names to the source code. +* Non-debug metadata is defined to be safe to drop, so a valid way to upgrade + it is to drop it. That is not very user friendly and a bit more effort is + expected, but no promises are made. .. _copyright-license-patents: @@ -494,12 +537,12 @@ 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 +Note that the LLVM Project does distribute dragonegg, **which is +GPL.** This means that anything "linked" into dragonegg 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 +that **any code linked into dragonegg 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 +into dragonegg 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.