1*9880d681SAndroid Build Coastguard Worker===================== 2*9880d681SAndroid Build Coastguard WorkerLLVM Developer Policy 3*9880d681SAndroid Build Coastguard Worker===================== 4*9880d681SAndroid Build Coastguard Worker 5*9880d681SAndroid Build Coastguard Worker.. contents:: 6*9880d681SAndroid Build Coastguard Worker :local: 7*9880d681SAndroid Build Coastguard Worker 8*9880d681SAndroid Build Coastguard WorkerIntroduction 9*9880d681SAndroid Build Coastguard Worker============ 10*9880d681SAndroid Build Coastguard Worker 11*9880d681SAndroid Build Coastguard WorkerThis document contains the LLVM Developer Policy which defines the project's 12*9880d681SAndroid Build Coastguard Workerpolicy towards developers and their contributions. The intent of this policy is 13*9880d681SAndroid Build Coastguard Workerto eliminate miscommunication, rework, and confusion that might arise from the 14*9880d681SAndroid Build Coastguard Workerdistributed nature of LLVM's development. By stating the policy in clear terms, 15*9880d681SAndroid Build Coastguard Workerwe hope each developer can know ahead of time what to expect when making LLVM 16*9880d681SAndroid Build Coastguard Workercontributions. This policy covers all llvm.org subprojects, including Clang, 17*9880d681SAndroid Build Coastguard WorkerLLDB, libc++, etc. 18*9880d681SAndroid Build Coastguard Worker 19*9880d681SAndroid Build Coastguard WorkerThis policy is also designed to accomplish the following objectives: 20*9880d681SAndroid Build Coastguard Worker 21*9880d681SAndroid Build Coastguard Worker#. Attract both users and developers to the LLVM project. 22*9880d681SAndroid Build Coastguard Worker 23*9880d681SAndroid Build Coastguard Worker#. Make life as simple and easy for contributors as possible. 24*9880d681SAndroid Build Coastguard Worker 25*9880d681SAndroid Build Coastguard Worker#. Keep the top of Subversion trees as stable as possible. 26*9880d681SAndroid Build Coastguard Worker 27*9880d681SAndroid Build Coastguard Worker#. Establish awareness of the project's :ref:`copyright, license, and patent 28*9880d681SAndroid Build Coastguard Worker policies <copyright-license-patents>` with contributors to the project. 29*9880d681SAndroid Build Coastguard Worker 30*9880d681SAndroid Build Coastguard WorkerThis policy is aimed at frequent contributors to LLVM. People interested in 31*9880d681SAndroid Build Coastguard Workercontributing one-off patches can do so in an informal way by sending them to the 32*9880d681SAndroid Build Coastguard Worker`llvm-commits mailing list 33*9880d681SAndroid Build Coastguard Worker<http://lists.llvm.org/mailman/listinfo/llvm-commits>`_ and engaging another 34*9880d681SAndroid Build Coastguard Workerdeveloper to see it through the process. 35*9880d681SAndroid Build Coastguard Worker 36*9880d681SAndroid Build Coastguard WorkerDeveloper Policies 37*9880d681SAndroid Build Coastguard Worker================== 38*9880d681SAndroid Build Coastguard Worker 39*9880d681SAndroid Build Coastguard WorkerThis section contains policies that pertain to frequent LLVM developers. We 40*9880d681SAndroid Build Coastguard Workeralways welcome `one-off patches`_ from people who do not routinely contribute to 41*9880d681SAndroid Build Coastguard WorkerLLVM, but we expect more from frequent contributors to keep the system as 42*9880d681SAndroid Build Coastguard Workerefficient as possible for everyone. Frequent LLVM contributors are expected to 43*9880d681SAndroid Build Coastguard Workermeet the following requirements in order for LLVM to maintain a high standard of 44*9880d681SAndroid Build Coastguard Workerquality. 45*9880d681SAndroid Build Coastguard Worker 46*9880d681SAndroid Build Coastguard WorkerStay Informed 47*9880d681SAndroid Build Coastguard Worker------------- 48*9880d681SAndroid Build Coastguard Worker 49*9880d681SAndroid Build Coastguard WorkerDevelopers should stay informed by reading at least the "dev" mailing list for 50*9880d681SAndroid Build Coastguard Workerthe projects you are interested in, such as `llvm-dev 51*9880d681SAndroid Build Coastguard Worker<http://lists.llvm.org/mailman/listinfo/llvm-dev>`_ for LLVM, `cfe-dev 52*9880d681SAndroid Build Coastguard Worker<http://lists.llvm.org/mailman/listinfo/cfe-dev>`_ for Clang, or `lldb-dev 53*9880d681SAndroid Build Coastguard Worker<http://lists.llvm.org/mailman/listinfo/lldb-dev>`_ for LLDB. If you are 54*9880d681SAndroid Build Coastguard Workerdoing anything more than just casual work on LLVM, it is suggested that you also 55*9880d681SAndroid Build Coastguard Workersubscribe to the "commits" mailing list for the subproject you're interested in, 56*9880d681SAndroid Build Coastguard Workersuch as `llvm-commits 57*9880d681SAndroid Build Coastguard Worker<http://lists.llvm.org/mailman/listinfo/llvm-commits>`_, `cfe-commits 58*9880d681SAndroid Build Coastguard Worker<http://lists.llvm.org/mailman/listinfo/cfe-commits>`_, or `lldb-commits 59*9880d681SAndroid Build Coastguard Worker<http://lists.llvm.org/mailman/listinfo/lldb-commits>`_. Reading the 60*9880d681SAndroid Build Coastguard Worker"commits" list and paying attention to changes being made by others is a good 61*9880d681SAndroid Build Coastguard Workerway to see what other people are interested in and watching the flow of the 62*9880d681SAndroid Build Coastguard Workerproject as a whole. 63*9880d681SAndroid Build Coastguard Worker 64*9880d681SAndroid Build Coastguard WorkerWe recommend that active developers register an email account with `LLVM 65*9880d681SAndroid Build Coastguard WorkerBugzilla <http://llvm.org/bugs/>`_ and preferably subscribe to the `llvm-bugs 66*9880d681SAndroid Build Coastguard Worker<http://lists.llvm.org/mailman/listinfo/llvm-bugs>`_ email list to keep track 67*9880d681SAndroid Build Coastguard Workerof bugs and enhancements occurring in LLVM. We really appreciate people who are 68*9880d681SAndroid Build Coastguard Workerproactive at catching incoming bugs in their components and dealing with them 69*9880d681SAndroid Build Coastguard Workerpromptly. 70*9880d681SAndroid Build Coastguard Worker 71*9880d681SAndroid Build Coastguard WorkerPlease be aware that all public LLVM mailing lists are public and archived, and 72*9880d681SAndroid Build Coastguard Workerthat notices of confidentiality or non-disclosure cannot be respected. 73*9880d681SAndroid Build Coastguard Worker 74*9880d681SAndroid Build Coastguard Worker.. _patch: 75*9880d681SAndroid Build Coastguard Worker.. _one-off patches: 76*9880d681SAndroid Build Coastguard Worker 77*9880d681SAndroid Build Coastguard WorkerMaking and Submitting a Patch 78*9880d681SAndroid Build Coastguard Worker----------------------------- 79*9880d681SAndroid Build Coastguard Worker 80*9880d681SAndroid Build Coastguard WorkerWhen making a patch for review, the goal is to make it as easy for the reviewer 81*9880d681SAndroid Build Coastguard Workerto read it as possible. As such, we recommend that you: 82*9880d681SAndroid Build Coastguard Worker 83*9880d681SAndroid Build Coastguard Worker#. Make your patch against the Subversion trunk, not a branch, and not an old 84*9880d681SAndroid Build Coastguard Worker version of LLVM. This makes it easy to apply the patch. For information on 85*9880d681SAndroid Build Coastguard Worker how to check out SVN trunk, please see the `Getting Started 86*9880d681SAndroid Build Coastguard Worker Guide <GettingStarted.html#checkout>`_. 87*9880d681SAndroid Build Coastguard Worker 88*9880d681SAndroid Build Coastguard Worker#. Similarly, patches should be submitted soon after they are generated. Old 89*9880d681SAndroid Build Coastguard Worker patches may not apply correctly if the underlying code changes between the 90*9880d681SAndroid Build Coastguard Worker time the patch was created and the time it is applied. 91*9880d681SAndroid Build Coastguard Worker 92*9880d681SAndroid Build Coastguard Worker#. Patches should be made with ``svn diff``, or similar. If you use a 93*9880d681SAndroid Build Coastguard Worker different tool, make sure it uses the ``diff -u`` format and that it 94*9880d681SAndroid Build Coastguard Worker doesn't contain clutter which makes it hard to read. 95*9880d681SAndroid Build Coastguard Worker 96*9880d681SAndroid Build Coastguard Worker#. If you are modifying generated files, such as the top-level ``configure`` 97*9880d681SAndroid Build Coastguard Worker script, please separate out those changes into a separate patch from the rest 98*9880d681SAndroid Build Coastguard Worker of your changes. 99*9880d681SAndroid Build Coastguard Worker 100*9880d681SAndroid Build Coastguard WorkerOnce your patch is ready, submit it by emailing it to the appropriate project's 101*9880d681SAndroid Build Coastguard Workercommit mailing list (or commit it directly if applicable). Alternatively, some 102*9880d681SAndroid Build Coastguard Workerpatches get sent to the project's development list or component of the LLVM bug 103*9880d681SAndroid Build Coastguard Workertracker, but the commit list is the primary place for reviews and should 104*9880d681SAndroid Build Coastguard Workergenerally be preferred. 105*9880d681SAndroid Build Coastguard Worker 106*9880d681SAndroid Build Coastguard WorkerWhen sending a patch to a mailing list, it is a good idea to send it as an 107*9880d681SAndroid Build Coastguard Worker*attachment* to the message, not embedded into the text of the message. This 108*9880d681SAndroid Build Coastguard Workerensures that your mailer will not mangle the patch when it sends it (e.g. by 109*9880d681SAndroid Build Coastguard Workermaking whitespace changes or by wrapping lines). 110*9880d681SAndroid Build Coastguard Worker 111*9880d681SAndroid Build Coastguard Worker*For Thunderbird users:* Before submitting a patch, please open *Preferences > 112*9880d681SAndroid Build Coastguard WorkerAdvanced > General > Config Editor*, find the key 113*9880d681SAndroid Build Coastguard Worker``mail.content_disposition_type``, and set its value to ``1``. Without this 114*9880d681SAndroid Build Coastguard Workersetting, Thunderbird sends your attachment using ``Content-Disposition: inline`` 115*9880d681SAndroid Build Coastguard Workerrather than ``Content-Disposition: attachment``. Apple Mail gamely displays such 116*9880d681SAndroid Build Coastguard Workera file inline, making it difficult to work with for reviewers using that 117*9880d681SAndroid Build Coastguard Workerprogram. 118*9880d681SAndroid Build Coastguard Worker 119*9880d681SAndroid Build Coastguard WorkerWhen submitting patches, please do not add confidentiality or non-disclosure 120*9880d681SAndroid Build Coastguard Workernotices to the patches themselves. These notices conflict with the `LLVM 121*9880d681SAndroid Build Coastguard WorkerLicense`_ and may result in your contribution being excluded. 122*9880d681SAndroid Build Coastguard Worker 123*9880d681SAndroid Build Coastguard Worker.. _code review: 124*9880d681SAndroid Build Coastguard Worker 125*9880d681SAndroid Build Coastguard WorkerCode Reviews 126*9880d681SAndroid Build Coastguard Worker------------ 127*9880d681SAndroid Build Coastguard Worker 128*9880d681SAndroid Build Coastguard WorkerLLVM has a code review policy. Code review is one way to increase the quality of 129*9880d681SAndroid Build Coastguard Workersoftware. We generally follow these policies: 130*9880d681SAndroid Build Coastguard Worker 131*9880d681SAndroid Build Coastguard Worker#. All developers are required to have significant changes reviewed before they 132*9880d681SAndroid Build Coastguard Worker are committed to the repository. 133*9880d681SAndroid Build Coastguard Worker 134*9880d681SAndroid Build Coastguard Worker#. Code reviews are conducted by email on the relevant project's commit mailing 135*9880d681SAndroid Build Coastguard Worker list, or alternatively on the project's development list or bug tracker. 136*9880d681SAndroid Build Coastguard Worker 137*9880d681SAndroid Build Coastguard Worker#. Code can be reviewed either before it is committed or after. We expect major 138*9880d681SAndroid Build Coastguard Worker changes to be reviewed before being committed, but smaller changes (or 139*9880d681SAndroid Build Coastguard Worker changes where the developer owns the component) can be reviewed after commit. 140*9880d681SAndroid Build Coastguard Worker 141*9880d681SAndroid Build Coastguard Worker#. The developer responsible for a code change is also responsible for making 142*9880d681SAndroid Build Coastguard Worker all necessary review-related changes. 143*9880d681SAndroid Build Coastguard Worker 144*9880d681SAndroid Build Coastguard Worker#. Code review can be an iterative process, which continues until the patch is 145*9880d681SAndroid Build Coastguard Worker ready to be committed. Specifically, once a patch is sent out for review, it 146*9880d681SAndroid Build Coastguard Worker needs an explicit "looks good" before it is submitted. Do not assume silent 147*9880d681SAndroid Build Coastguard Worker approval, or request active objections to the patch with a deadline. 148*9880d681SAndroid Build Coastguard Worker 149*9880d681SAndroid Build Coastguard WorkerSometimes code reviews will take longer than you would hope for, especially for 150*9880d681SAndroid Build Coastguard Workerlarger features. Accepted ways to speed up review times for your patches are: 151*9880d681SAndroid Build Coastguard Worker 152*9880d681SAndroid Build Coastguard Worker* Review other people's patches. If you help out, everybody will be more 153*9880d681SAndroid Build Coastguard Worker willing to do the same for you; goodwill is our currency. 154*9880d681SAndroid Build Coastguard Worker* Ping the patch. If it is urgent, provide reasons why it is important to you to 155*9880d681SAndroid Build Coastguard Worker get this patch landed and ping it every couple of days. If it is 156*9880d681SAndroid Build Coastguard Worker not urgent, the common courtesy ping rate is one week. Remember that you're 157*9880d681SAndroid Build Coastguard Worker asking for valuable time from other professional developers. 158*9880d681SAndroid Build Coastguard Worker* Ask for help on IRC. Developers on IRC will be able to either help you 159*9880d681SAndroid Build Coastguard Worker directly, or tell you who might be a good reviewer. 160*9880d681SAndroid Build Coastguard Worker* Split your patch into multiple smaller patches that build on each other. The 161*9880d681SAndroid Build Coastguard Worker smaller your patch, the higher the probability that somebody will take a quick 162*9880d681SAndroid Build Coastguard Worker look at it. 163*9880d681SAndroid Build Coastguard Worker 164*9880d681SAndroid Build Coastguard WorkerDevelopers should participate in code reviews as both reviewers and 165*9880d681SAndroid Build Coastguard Workerreviewees. If someone is kind enough to review your code, you should return the 166*9880d681SAndroid Build Coastguard Workerfavor for someone else. Note that anyone is welcome to review and give feedback 167*9880d681SAndroid Build Coastguard Workeron a patch, but only people with Subversion write access can approve it. 168*9880d681SAndroid Build Coastguard Worker 169*9880d681SAndroid Build Coastguard WorkerThere is a web based code review tool that can optionally be used 170*9880d681SAndroid Build Coastguard Workerfor code reviews. See :doc:`Phabricator`. 171*9880d681SAndroid Build Coastguard Worker 172*9880d681SAndroid Build Coastguard WorkerCode Owners 173*9880d681SAndroid Build Coastguard Worker----------- 174*9880d681SAndroid Build Coastguard Worker 175*9880d681SAndroid Build Coastguard WorkerThe LLVM Project relies on two features of its process to maintain rapid 176*9880d681SAndroid Build Coastguard Workerdevelopment in addition to the high quality of its source base: the combination 177*9880d681SAndroid Build Coastguard Workerof code review plus post-commit review for trusted maintainers. Having both is 178*9880d681SAndroid Build Coastguard Workera great way for the project to take advantage of the fact that most people do 179*9880d681SAndroid Build Coastguard Workerthe right thing most of the time, and only commit patches without pre-commit 180*9880d681SAndroid Build Coastguard Workerreview when they are confident they are right. 181*9880d681SAndroid Build Coastguard Worker 182*9880d681SAndroid Build Coastguard WorkerThe trick to this is that the project has to guarantee that all patches that are 183*9880d681SAndroid Build Coastguard Workercommitted are reviewed after they go in: you don't want everyone to assume 184*9880d681SAndroid Build Coastguard Workersomeone else will review it, allowing the patch to go unreviewed. To solve this 185*9880d681SAndroid Build Coastguard Workerproblem, we have a notion of an 'owner' for a piece of the code. The sole 186*9880d681SAndroid Build Coastguard Workerresponsibility of a code owner is to ensure that a commit to their area of the 187*9880d681SAndroid Build Coastguard Workercode is appropriately reviewed, either by themself or by someone else. The list 188*9880d681SAndroid Build Coastguard Workerof current code owners can be found in the file 189*9880d681SAndroid Build Coastguard Worker`CODE_OWNERS.TXT <http://llvm.org/klaus/llvm/blob/master/CODE_OWNERS.TXT>`_ 190*9880d681SAndroid Build Coastguard Workerin the root of the LLVM source tree. 191*9880d681SAndroid Build Coastguard Worker 192*9880d681SAndroid Build Coastguard WorkerNote that code ownership is completely different than reviewers: anyone can 193*9880d681SAndroid Build Coastguard Workerreview a piece of code, and we welcome code review from anyone who is 194*9880d681SAndroid Build Coastguard Workerinterested. Code owners are the "last line of defense" to guarantee that all 195*9880d681SAndroid Build Coastguard Workerpatches that are committed are actually reviewed. 196*9880d681SAndroid Build Coastguard Worker 197*9880d681SAndroid Build Coastguard WorkerBeing a code owner is a somewhat unglamorous position, but it is incredibly 198*9880d681SAndroid Build Coastguard Workerimportant for the ongoing success of the project. Because people get busy, 199*9880d681SAndroid Build Coastguard Workerinterests change, and unexpected things happen, code ownership is purely opt-in, 200*9880d681SAndroid Build Coastguard Workerand anyone can choose to resign their "title" at any time. For now, we do not 201*9880d681SAndroid Build Coastguard Workerhave an official policy on how one gets elected to be a code owner. 202*9880d681SAndroid Build Coastguard Worker 203*9880d681SAndroid Build Coastguard Worker.. _include a testcase: 204*9880d681SAndroid Build Coastguard Worker 205*9880d681SAndroid Build Coastguard WorkerTest Cases 206*9880d681SAndroid Build Coastguard Worker---------- 207*9880d681SAndroid Build Coastguard Worker 208*9880d681SAndroid Build Coastguard WorkerDevelopers are required to create test cases for any bugs fixed and any new 209*9880d681SAndroid Build Coastguard Workerfeatures added. Some tips for getting your testcase approved: 210*9880d681SAndroid Build Coastguard Worker 211*9880d681SAndroid Build Coastguard Worker* All feature and regression test cases are added to the ``llvm/test`` 212*9880d681SAndroid Build Coastguard Worker directory. The appropriate sub-directory should be selected (see the 213*9880d681SAndroid Build Coastguard Worker :doc:`Testing Guide <TestingGuide>` for details). 214*9880d681SAndroid Build Coastguard Worker 215*9880d681SAndroid Build Coastguard Worker* Test cases should be written in :doc:`LLVM assembly language <LangRef>`. 216*9880d681SAndroid Build Coastguard Worker 217*9880d681SAndroid Build Coastguard Worker* Test cases, especially for regressions, should be reduced as much as possible, 218*9880d681SAndroid Build Coastguard Worker by :doc:`bugpoint <Bugpoint>` or manually. It is unacceptable to place an 219*9880d681SAndroid Build Coastguard Worker entire failing program into ``llvm/test`` as this creates a *time-to-test* 220*9880d681SAndroid Build Coastguard Worker burden on all developers. Please keep them short. 221*9880d681SAndroid Build Coastguard Worker 222*9880d681SAndroid Build Coastguard WorkerNote that llvm/test and clang/test are designed for regression and small feature 223*9880d681SAndroid Build Coastguard Workertests only. More extensive test cases (e.g., entire applications, benchmarks, 224*9880d681SAndroid Build Coastguard Workeretc) should be added to the ``llvm-test`` test suite. The llvm-test suite is 225*9880d681SAndroid Build Coastguard Workerfor coverage (correctness, performance, etc) testing, not feature or regression 226*9880d681SAndroid Build Coastguard Workertesting. 227*9880d681SAndroid Build Coastguard Worker 228*9880d681SAndroid Build Coastguard WorkerQuality 229*9880d681SAndroid Build Coastguard Worker------- 230*9880d681SAndroid Build Coastguard Worker 231*9880d681SAndroid Build Coastguard WorkerThe minimum quality standards that any change must satisfy before being 232*9880d681SAndroid Build Coastguard Workercommitted to the main development branch are: 233*9880d681SAndroid Build Coastguard Worker 234*9880d681SAndroid Build Coastguard Worker#. Code must adhere to the `LLVM Coding Standards <CodingStandards.html>`_. 235*9880d681SAndroid Build Coastguard Worker 236*9880d681SAndroid Build Coastguard Worker#. Code must compile cleanly (no errors, no warnings) on at least one platform. 237*9880d681SAndroid Build Coastguard Worker 238*9880d681SAndroid Build Coastguard Worker#. Bug fixes and new features should `include a testcase`_ so we know if the 239*9880d681SAndroid Build Coastguard Worker fix/feature ever regresses in the future. 240*9880d681SAndroid Build Coastguard Worker 241*9880d681SAndroid Build Coastguard Worker#. Code must pass the ``llvm/test`` test suite. 242*9880d681SAndroid Build Coastguard Worker 243*9880d681SAndroid Build Coastguard Worker#. The code must not cause regressions on a reasonable subset of llvm-test, 244*9880d681SAndroid Build Coastguard Worker where "reasonable" depends on the contributor's judgement and the scope of 245*9880d681SAndroid Build Coastguard Worker the change (more invasive changes require more testing). A reasonable subset 246*9880d681SAndroid Build Coastguard Worker might be something like "``llvm-test/MultiSource/Benchmarks``". 247*9880d681SAndroid Build Coastguard Worker 248*9880d681SAndroid Build Coastguard WorkerAdditionally, the committer is responsible for addressing any problems found in 249*9880d681SAndroid Build Coastguard Workerthe future that the change is responsible for. For example: 250*9880d681SAndroid Build Coastguard Worker 251*9880d681SAndroid Build Coastguard Worker* The code should compile cleanly on all supported platforms. 252*9880d681SAndroid Build Coastguard Worker 253*9880d681SAndroid Build Coastguard Worker* The changes should not cause any correctness regressions in the ``llvm-test`` 254*9880d681SAndroid Build Coastguard Worker suite and must not cause any major performance regressions. 255*9880d681SAndroid Build Coastguard Worker 256*9880d681SAndroid Build Coastguard Worker* The change set should not cause performance or correctness regressions for the 257*9880d681SAndroid Build Coastguard Worker LLVM tools. 258*9880d681SAndroid Build Coastguard Worker 259*9880d681SAndroid Build Coastguard Worker* The changes should not cause performance or correctness regressions in code 260*9880d681SAndroid Build Coastguard Worker compiled by LLVM on all applicable targets. 261*9880d681SAndroid Build Coastguard Worker 262*9880d681SAndroid Build Coastguard Worker* You are expected to address any `Bugzilla bugs <http://llvm.org/bugs/>`_ that 263*9880d681SAndroid Build Coastguard Worker result from your change. 264*9880d681SAndroid Build Coastguard Worker 265*9880d681SAndroid Build Coastguard WorkerWe prefer for this to be handled before submission but understand that it isn't 266*9880d681SAndroid Build Coastguard Workerpossible to test all of this for every submission. Our build bots and nightly 267*9880d681SAndroid Build Coastguard Workertesting infrastructure normally finds these problems. A good rule of thumb is 268*9880d681SAndroid Build Coastguard Workerto check the nightly testers for regressions the day after your change. Build 269*9880d681SAndroid Build Coastguard Workerbots will directly email you if a group of commits that included yours caused a 270*9880d681SAndroid Build Coastguard Workerfailure. You are expected to check the build bot messages to see if they are 271*9880d681SAndroid Build Coastguard Workeryour fault and, if so, fix the breakage. 272*9880d681SAndroid Build Coastguard Worker 273*9880d681SAndroid Build Coastguard WorkerCommits that violate these quality standards (e.g. are very broken) may be 274*9880d681SAndroid Build Coastguard Workerreverted. This is necessary when the change blocks other developers from making 275*9880d681SAndroid Build Coastguard Workerprogress. The developer is welcome to re-commit the change after the problem has 276*9880d681SAndroid Build Coastguard Workerbeen fixed. 277*9880d681SAndroid Build Coastguard Worker 278*9880d681SAndroid Build Coastguard Worker.. _commit messages: 279*9880d681SAndroid Build Coastguard Worker 280*9880d681SAndroid Build Coastguard WorkerCommit messages 281*9880d681SAndroid Build Coastguard Worker--------------- 282*9880d681SAndroid Build Coastguard Worker 283*9880d681SAndroid Build Coastguard WorkerAlthough we don't enforce the format of commit messages, we prefer that 284*9880d681SAndroid Build Coastguard Workeryou follow these guidelines to help review, search in logs, email formatting 285*9880d681SAndroid Build Coastguard Workerand so on. These guidelines are very similar to rules used by other open source 286*9880d681SAndroid Build Coastguard Workerprojects. 287*9880d681SAndroid Build Coastguard Worker 288*9880d681SAndroid Build Coastguard WorkerMost importantly, the contents of the message should be carefully written to 289*9880d681SAndroid Build Coastguard Workerconvey the rationale of the change (without delving too much in detail). It 290*9880d681SAndroid Build Coastguard Workeralso should avoid being vague or overly specific. For example, "bits were not 291*9880d681SAndroid Build Coastguard Workerset right" will leave the reviewer wondering about which bits, and why they 292*9880d681SAndroid Build Coastguard Workerweren't right, while "Correctly set overflow bits in TargetInfo" conveys almost 293*9880d681SAndroid Build Coastguard Workerall there is to the change. 294*9880d681SAndroid Build Coastguard Worker 295*9880d681SAndroid Build Coastguard WorkerBelow are some guidelines about the format of the message itself: 296*9880d681SAndroid Build Coastguard Worker 297*9880d681SAndroid Build Coastguard Worker* Separate the commit message into title, body and, if you're not the original 298*9880d681SAndroid Build Coastguard Worker author, a "Patch by" attribution line (see below). 299*9880d681SAndroid Build Coastguard Worker 300*9880d681SAndroid Build Coastguard Worker* The title should be concise. Because all commits are emailed to the list with 301*9880d681SAndroid Build Coastguard Worker the first line as the subject, long titles are frowned upon. Short titles 302*9880d681SAndroid Build Coastguard Worker also look better in `git log`. 303*9880d681SAndroid Build Coastguard Worker 304*9880d681SAndroid Build Coastguard Worker* When the changes are restricted to a specific part of the code (e.g. a 305*9880d681SAndroid Build Coastguard Worker back-end or optimization pass), it is customary to add a tag to the 306*9880d681SAndroid Build Coastguard Worker beginning of the line in square brackets. For example, "[SCEV] ..." 307*9880d681SAndroid Build Coastguard Worker or "[OpenMP] ...". This helps email filters and searches for post-commit 308*9880d681SAndroid Build Coastguard Worker reviews. 309*9880d681SAndroid Build Coastguard Worker 310*9880d681SAndroid Build Coastguard Worker* The body, if it exists, should be separated from the title by an empty line. 311*9880d681SAndroid Build Coastguard Worker 312*9880d681SAndroid Build Coastguard Worker* The body should be concise, but explanatory, including a complete 313*9880d681SAndroid Build Coastguard Worker reasoning. Unless it is required to understand the change, examples, 314*9880d681SAndroid Build Coastguard Worker code snippets and gory details should be left to bug comments, web 315*9880d681SAndroid Build Coastguard Worker review or the mailing list. 316*9880d681SAndroid Build Coastguard Worker 317*9880d681SAndroid Build Coastguard Worker* If the patch fixes a bug in bugzilla, please include the PR# in the message. 318*9880d681SAndroid Build Coastguard Worker 319*9880d681SAndroid Build Coastguard Worker* `Attribution of Changes`_ should be in a separate line, after the end of 320*9880d681SAndroid Build Coastguard Worker the body, as simple as "Patch by John Doe.". This is how we officially 321*9880d681SAndroid Build Coastguard Worker handle attribution, and there are automated processes that rely on this 322*9880d681SAndroid Build Coastguard Worker format. 323*9880d681SAndroid Build Coastguard Worker 324*9880d681SAndroid Build Coastguard Worker* Text formatting and spelling should follow the same rules as documentation 325*9880d681SAndroid Build Coastguard Worker and in-code comments, ex. capitalization, full stop, etc. 326*9880d681SAndroid Build Coastguard Worker 327*9880d681SAndroid Build Coastguard Worker* If the commit is a bug fix on top of another recently committed patch, or a 328*9880d681SAndroid Build Coastguard Worker revert or reapply of a patch, include the svn revision number of the prior 329*9880d681SAndroid Build Coastguard Worker related commit. This could be as simple as "Revert rNNNN because it caused 330*9880d681SAndroid Build Coastguard Worker PR#". 331*9880d681SAndroid Build Coastguard Worker 332*9880d681SAndroid Build Coastguard WorkerFor minor violations of these recommendations, the community normally favors 333*9880d681SAndroid Build Coastguard Workerreminding the contributor of this policy over reverting. Minor corrections and 334*9880d681SAndroid Build Coastguard Workeromissions can be handled by sending a reply to the commits mailing list. 335*9880d681SAndroid Build Coastguard Worker 336*9880d681SAndroid Build Coastguard WorkerObtaining Commit Access 337*9880d681SAndroid Build Coastguard Worker----------------------- 338*9880d681SAndroid Build Coastguard Worker 339*9880d681SAndroid Build Coastguard WorkerWe grant commit access to contributors with a track record of submitting high 340*9880d681SAndroid Build Coastguard Workerquality patches. If you would like commit access, please send an email to 341*9880d681SAndroid Build Coastguard Worker`Chris <mailto:[email protected]>`_ with the following information: 342*9880d681SAndroid Build Coastguard Worker 343*9880d681SAndroid Build Coastguard Worker#. The user name you want to commit with, e.g. "hacker". 344*9880d681SAndroid Build Coastguard Worker 345*9880d681SAndroid Build Coastguard Worker#. The full name and email address you want message to llvm-commits to come 346*9880d681SAndroid Build Coastguard Worker from, e.g. "J. Random Hacker <[email protected]>". 347*9880d681SAndroid Build Coastguard Worker 348*9880d681SAndroid Build Coastguard Worker#. A "password hash" of the password you want to use, e.g. "``2ACR96qjUqsyM``". 349*9880d681SAndroid Build Coastguard Worker Note that you don't ever tell us what your password is; you just give it to 350*9880d681SAndroid Build Coastguard Worker us in an encrypted form. To get this, run "``htpasswd``" (a utility that 351*9880d681SAndroid Build Coastguard Worker comes with apache) in *crypt* mode (often enabled with "``-d``"), or find a web 352*9880d681SAndroid Build Coastguard Worker page that will do it for you. Note that our system does not work with MD5 353*9880d681SAndroid Build Coastguard Worker hashes. These are significantly longer than a crypt hash - e.g. 354*9880d681SAndroid Build Coastguard Worker "``$apr1$vea6bBV2$Z8IFx.AfeD8LhqlZFqJer0``", we only accept the shorter crypt hash. 355*9880d681SAndroid Build Coastguard Worker 356*9880d681SAndroid Build Coastguard WorkerOnce you've been granted commit access, you should be able to check out an LLVM 357*9880d681SAndroid Build Coastguard Workertree with an SVN URL of "https://[email protected]/..." instead of the normal 358*9880d681SAndroid Build Coastguard Workeranonymous URL of "http://llvm.org/...". The first time you commit you'll have 359*9880d681SAndroid Build Coastguard Workerto type in your password. Note that you may get a warning from SVN about an 360*9880d681SAndroid Build Coastguard Workeruntrusted key; you can ignore this. To verify that your commit access works, 361*9880d681SAndroid Build Coastguard Workerplease do a test commit (e.g. change a comment or add a blank line). Your first 362*9880d681SAndroid Build Coastguard Workercommit to a repository may require the autogenerated email to be approved by a 363*9880d681SAndroid Build Coastguard Workermailing list. This is normal and will be done when the mailing list owner has 364*9880d681SAndroid Build Coastguard Workertime. 365*9880d681SAndroid Build Coastguard Worker 366*9880d681SAndroid Build Coastguard WorkerIf you have recently been granted commit access, these policies apply: 367*9880d681SAndroid Build Coastguard Worker 368*9880d681SAndroid Build Coastguard Worker#. You are granted *commit-after-approval* to all parts of LLVM. To get 369*9880d681SAndroid Build Coastguard Worker approval, submit a `patch`_ to `llvm-commits 370*9880d681SAndroid Build Coastguard Worker <http://lists.llvm.org/mailman/listinfo/llvm-commits>`_. When approved, 371*9880d681SAndroid Build Coastguard Worker you may commit it yourself. 372*9880d681SAndroid Build Coastguard Worker 373*9880d681SAndroid Build Coastguard Worker#. You are allowed to commit patches without approval which you think are 374*9880d681SAndroid Build Coastguard Worker obvious. This is clearly a subjective decision --- we simply expect you to 375*9880d681SAndroid Build Coastguard Worker use good judgement. Examples include: fixing build breakage, reverting 376*9880d681SAndroid Build Coastguard Worker obviously broken patches, documentation/comment changes, any other minor 377*9880d681SAndroid Build Coastguard Worker changes. 378*9880d681SAndroid Build Coastguard Worker 379*9880d681SAndroid Build Coastguard Worker#. You are allowed to commit patches without approval to those portions of LLVM 380*9880d681SAndroid Build Coastguard Worker that you have contributed or maintain (i.e., have been assigned 381*9880d681SAndroid Build Coastguard Worker responsibility for), with the proviso that such commits must not break the 382*9880d681SAndroid Build Coastguard Worker build. This is a "trust but verify" policy, and commits of this nature are 383*9880d681SAndroid Build Coastguard Worker reviewed after they are committed. 384*9880d681SAndroid Build Coastguard Worker 385*9880d681SAndroid Build Coastguard Worker#. Multiple violations of these policies or a single egregious violation may 386*9880d681SAndroid Build Coastguard Worker cause commit access to be revoked. 387*9880d681SAndroid Build Coastguard Worker 388*9880d681SAndroid Build Coastguard WorkerIn any case, your changes are still subject to `code review`_ (either before or 389*9880d681SAndroid Build Coastguard Workerafter they are committed, depending on the nature of the change). You are 390*9880d681SAndroid Build Coastguard Workerencouraged to review other peoples' patches as well, but you aren't required 391*9880d681SAndroid Build Coastguard Workerto do so. 392*9880d681SAndroid Build Coastguard Worker 393*9880d681SAndroid Build Coastguard Worker.. _discuss the change/gather consensus: 394*9880d681SAndroid Build Coastguard Worker 395*9880d681SAndroid Build Coastguard WorkerMaking a Major Change 396*9880d681SAndroid Build Coastguard Worker--------------------- 397*9880d681SAndroid Build Coastguard Worker 398*9880d681SAndroid Build Coastguard WorkerWhen a developer begins a major new project with the aim of contributing it back 399*9880d681SAndroid Build Coastguard Workerto LLVM, they should inform the community with an email to the `llvm-dev 400*9880d681SAndroid Build Coastguard Worker<http://lists.llvm.org/mailman/listinfo/llvm-dev>`_ email list, to the extent 401*9880d681SAndroid Build Coastguard Workerpossible. The reason for this is to: 402*9880d681SAndroid Build Coastguard Worker 403*9880d681SAndroid Build Coastguard Worker#. keep the community informed about future changes to LLVM, 404*9880d681SAndroid Build Coastguard Worker 405*9880d681SAndroid Build Coastguard Worker#. avoid duplication of effort by preventing multiple parties working on the 406*9880d681SAndroid Build Coastguard Worker same thing and not knowing about it, and 407*9880d681SAndroid Build Coastguard Worker 408*9880d681SAndroid Build Coastguard Worker#. ensure that any technical issues around the proposed work are discussed and 409*9880d681SAndroid Build Coastguard Worker resolved before any significant work is done. 410*9880d681SAndroid Build Coastguard Worker 411*9880d681SAndroid Build Coastguard WorkerThe design of LLVM is carefully controlled to ensure that all the pieces fit 412*9880d681SAndroid Build Coastguard Workertogether well and are as consistent as possible. If you plan to make a major 413*9880d681SAndroid Build Coastguard Workerchange to the way LLVM works or want to add a major new extension, it is a good 414*9880d681SAndroid Build Coastguard Workeridea to get consensus with the development community before you start working on 415*9880d681SAndroid Build Coastguard Workerit. 416*9880d681SAndroid Build Coastguard Worker 417*9880d681SAndroid Build Coastguard WorkerOnce the design of the new feature is finalized, the work itself should be done 418*9880d681SAndroid Build Coastguard Workeras a series of `incremental changes`_, not as a long-term development branch. 419*9880d681SAndroid Build Coastguard Worker 420*9880d681SAndroid Build Coastguard Worker.. _incremental changes: 421*9880d681SAndroid Build Coastguard Worker 422*9880d681SAndroid Build Coastguard WorkerIncremental Development 423*9880d681SAndroid Build Coastguard Worker----------------------- 424*9880d681SAndroid Build Coastguard Worker 425*9880d681SAndroid Build Coastguard WorkerIn the LLVM project, we do all significant changes as a series of incremental 426*9880d681SAndroid Build Coastguard Workerpatches. We have a strong dislike for huge changes or long-term development 427*9880d681SAndroid Build Coastguard Workerbranches. Long-term development branches have a number of drawbacks: 428*9880d681SAndroid Build Coastguard Worker 429*9880d681SAndroid Build Coastguard Worker#. Branches must have mainline merged into them periodically. If the branch 430*9880d681SAndroid Build Coastguard Worker development and mainline development occur in the same pieces of code, 431*9880d681SAndroid Build Coastguard Worker resolving merge conflicts can take a lot of time. 432*9880d681SAndroid Build Coastguard Worker 433*9880d681SAndroid Build Coastguard Worker#. Other people in the community tend to ignore work on branches. 434*9880d681SAndroid Build Coastguard Worker 435*9880d681SAndroid Build Coastguard Worker#. Huge changes (produced when a branch is merged back onto mainline) are 436*9880d681SAndroid Build Coastguard Worker extremely difficult to `code review`_. 437*9880d681SAndroid Build Coastguard Worker 438*9880d681SAndroid Build Coastguard Worker#. Branches are not routinely tested by our nightly tester infrastructure. 439*9880d681SAndroid Build Coastguard Worker 440*9880d681SAndroid Build Coastguard Worker#. Changes developed as monolithic large changes often don't work until the 441*9880d681SAndroid Build Coastguard Worker entire set of changes is done. Breaking it down into a set of smaller 442*9880d681SAndroid Build Coastguard Worker changes increases the odds that any of the work will be committed to the main 443*9880d681SAndroid Build Coastguard Worker repository. 444*9880d681SAndroid Build Coastguard Worker 445*9880d681SAndroid Build Coastguard WorkerTo address these problems, LLVM uses an incremental development style and we 446*9880d681SAndroid Build Coastguard Workerrequire contributors to follow this practice when making a large/invasive 447*9880d681SAndroid Build Coastguard Workerchange. Some tips: 448*9880d681SAndroid Build Coastguard Worker 449*9880d681SAndroid Build Coastguard Worker* Large/invasive changes usually have a number of secondary changes that are 450*9880d681SAndroid Build Coastguard Worker required before the big change can be made (e.g. API cleanup, etc). These 451*9880d681SAndroid Build Coastguard Worker sorts of changes can often be done before the major change is done, 452*9880d681SAndroid Build Coastguard Worker independently of that work. 453*9880d681SAndroid Build Coastguard Worker 454*9880d681SAndroid Build Coastguard Worker* The remaining inter-related work should be decomposed into unrelated sets of 455*9880d681SAndroid Build Coastguard Worker changes if possible. Once this is done, define the first increment and get 456*9880d681SAndroid Build Coastguard Worker consensus on what the end goal of the change is. 457*9880d681SAndroid Build Coastguard Worker 458*9880d681SAndroid Build Coastguard Worker* Each change in the set can be stand alone (e.g. to fix a bug), or part of a 459*9880d681SAndroid Build Coastguard Worker planned series of changes that works towards the development goal. 460*9880d681SAndroid Build Coastguard Worker 461*9880d681SAndroid Build Coastguard Worker* Each change should be kept as small as possible. This simplifies your work 462*9880d681SAndroid Build Coastguard Worker (into a logical progression), simplifies code review and reduces the chance 463*9880d681SAndroid Build Coastguard Worker that you will get negative feedback on the change. Small increments also 464*9880d681SAndroid Build Coastguard Worker facilitate the maintenance of a high quality code base. 465*9880d681SAndroid Build Coastguard Worker 466*9880d681SAndroid Build Coastguard Worker* Often, an independent precursor to a big change is to add a new API and slowly 467*9880d681SAndroid Build Coastguard Worker migrate clients to use the new API. Each change to use the new API is often 468*9880d681SAndroid Build Coastguard Worker "obvious" and can be committed without review. Once the new API is in place 469*9880d681SAndroid Build Coastguard Worker and used, it is much easier to replace the underlying implementation of the 470*9880d681SAndroid Build Coastguard Worker API. This implementation change is logically separate from the API 471*9880d681SAndroid Build Coastguard Worker change. 472*9880d681SAndroid Build Coastguard Worker 473*9880d681SAndroid Build Coastguard WorkerIf you are interested in making a large change, and this scares you, please make 474*9880d681SAndroid Build Coastguard Workersure to first `discuss the change/gather consensus`_ then ask about the best way 475*9880d681SAndroid Build Coastguard Workerto go about making the change. 476*9880d681SAndroid Build Coastguard Worker 477*9880d681SAndroid Build Coastguard WorkerAttribution of Changes 478*9880d681SAndroid Build Coastguard Worker---------------------- 479*9880d681SAndroid Build Coastguard Worker 480*9880d681SAndroid Build Coastguard WorkerWhen contributors submit a patch to an LLVM project, other developers with 481*9880d681SAndroid Build Coastguard Workercommit access may commit it for the author once appropriate (based on the 482*9880d681SAndroid Build Coastguard Workerprogression of code review, etc.). When doing so, it is important to retain 483*9880d681SAndroid Build Coastguard Workercorrect attribution of contributions to their contributors. However, we do not 484*9880d681SAndroid Build Coastguard Workerwant the source code to be littered with random attributions "this code written 485*9880d681SAndroid Build Coastguard Workerby J. Random Hacker" (this is noisy and distracting). In practice, the revision 486*9880d681SAndroid Build Coastguard Workercontrol system keeps a perfect history of who changed what, and the CREDITS.txt 487*9880d681SAndroid Build Coastguard Workerfile describes higher-level contributions. If you commit a patch for someone 488*9880d681SAndroid Build Coastguard Workerelse, please follow the attribution of changes in the simple manner as outlined 489*9880d681SAndroid Build Coastguard Workerby the `commit messages`_ section. Overall, please do not add contributor names 490*9880d681SAndroid Build Coastguard Workerto the source code. 491*9880d681SAndroid Build Coastguard Worker 492*9880d681SAndroid Build Coastguard WorkerAlso, don't commit patches authored by others unless they have submitted the 493*9880d681SAndroid Build Coastguard Workerpatch to the project or you have been authorized to submit them on their behalf 494*9880d681SAndroid Build Coastguard Worker(you work together and your company authorized you to contribute the patches, 495*9880d681SAndroid Build Coastguard Workeretc.). The author should first submit them to the relevant project's commit 496*9880d681SAndroid Build Coastguard Workerlist, development list, or LLVM bug tracker component. If someone sends you 497*9880d681SAndroid Build Coastguard Workera patch privately, encourage them to submit it to the appropriate list first. 498*9880d681SAndroid Build Coastguard Worker 499*9880d681SAndroid Build Coastguard Worker 500*9880d681SAndroid Build Coastguard WorkerIR Backwards Compatibility 501*9880d681SAndroid Build Coastguard Worker-------------------------- 502*9880d681SAndroid Build Coastguard Worker 503*9880d681SAndroid Build Coastguard WorkerWhen the IR format has to be changed, keep in mind that we try to maintain some 504*9880d681SAndroid Build Coastguard Workerbackwards compatibility. The rules are intended as a balance between convenience 505*9880d681SAndroid Build Coastguard Workerfor llvm users and not imposing a big burden on llvm developers: 506*9880d681SAndroid Build Coastguard Worker 507*9880d681SAndroid Build Coastguard Worker* The textual format is not backwards compatible. We don't change it too often, 508*9880d681SAndroid Build Coastguard Worker but there are no specific promises. 509*9880d681SAndroid Build Coastguard Worker 510*9880d681SAndroid Build Coastguard Worker* Additions and changes to the IR should be reflected in 511*9880d681SAndroid Build Coastguard Worker ``test/Bitcode/compatibility.ll``. 512*9880d681SAndroid Build Coastguard Worker 513*9880d681SAndroid Build Coastguard Worker* The bitcode format produced by a X.Y release will be readable by all 514*9880d681SAndroid Build Coastguard Worker following X.Z releases and the (X+1).0 release. 515*9880d681SAndroid Build Coastguard Worker 516*9880d681SAndroid Build Coastguard Worker* After each X.Y release, ``compatibility.ll`` must be copied to 517*9880d681SAndroid Build Coastguard Worker ``compatibility-X.Y.ll``. The corresponding bitcode file should be assembled 518*9880d681SAndroid Build Coastguard Worker using the X.Y build and committed as ``compatibility-X.Y.ll.bc``. 519*9880d681SAndroid Build Coastguard Worker 520*9880d681SAndroid Build Coastguard Worker* Newer releases can ignore features from older releases, but they cannot 521*9880d681SAndroid Build Coastguard Worker miscompile them. For example, if nsw is ever replaced with something else, 522*9880d681SAndroid Build Coastguard Worker dropping it would be a valid way to upgrade the IR. 523*9880d681SAndroid Build Coastguard Worker 524*9880d681SAndroid Build Coastguard Worker* Debug metadata is special in that it is currently dropped during upgrades. 525*9880d681SAndroid Build Coastguard Worker 526*9880d681SAndroid Build Coastguard Worker* Non-debug metadata is defined to be safe to drop, so a valid way to upgrade 527*9880d681SAndroid Build Coastguard Worker it is to drop it. That is not very user friendly and a bit more effort is 528*9880d681SAndroid Build Coastguard Worker expected, but no promises are made. 529*9880d681SAndroid Build Coastguard Worker 530*9880d681SAndroid Build Coastguard WorkerC API Changes 531*9880d681SAndroid Build Coastguard Worker---------------- 532*9880d681SAndroid Build Coastguard Worker 533*9880d681SAndroid Build Coastguard Worker* Stability Guarantees: The C API is, in general, a "best effort" for stability. 534*9880d681SAndroid Build Coastguard Worker This means that we make every attempt to keep the C API stable, but that 535*9880d681SAndroid Build Coastguard Worker stability will be limited by the abstractness of the interface and the 536*9880d681SAndroid Build Coastguard Worker stability of the C++ API that it wraps. In practice, this means that things 537*9880d681SAndroid Build Coastguard Worker like "create debug info" or "create this type of instruction" are likely to be 538*9880d681SAndroid Build Coastguard Worker less stable than "take this IR file and JIT it for my current machine". 539*9880d681SAndroid Build Coastguard Worker 540*9880d681SAndroid Build Coastguard Worker* Release stability: We won't break the C API on the release branch with patches 541*9880d681SAndroid Build Coastguard Worker that go on that branch, with the exception that we will fix an unintentional 542*9880d681SAndroid Build Coastguard Worker C API break that will keep the release consistent with both the previous and 543*9880d681SAndroid Build Coastguard Worker next release. 544*9880d681SAndroid Build Coastguard Worker 545*9880d681SAndroid Build Coastguard Worker* Testing: Patches to the C API are expected to come with tests just like any 546*9880d681SAndroid Build Coastguard Worker other patch. 547*9880d681SAndroid Build Coastguard Worker 548*9880d681SAndroid Build Coastguard Worker* Including new things into the API: If an LLVM subcomponent has a C API already 549*9880d681SAndroid Build Coastguard Worker included, then expanding that C API is acceptable. Adding C API for 550*9880d681SAndroid Build Coastguard Worker subcomponents that don't currently have one needs to be discussed on the 551*9880d681SAndroid Build Coastguard Worker mailing list for design and maintainability feedback prior to implementation. 552*9880d681SAndroid Build Coastguard Worker 553*9880d681SAndroid Build Coastguard Worker* Documentation: Any changes to the C API are required to be documented in the 554*9880d681SAndroid Build Coastguard Worker release notes so that it's clear to external users who do not follow the 555*9880d681SAndroid Build Coastguard Worker project how the C API is changing and evolving. 556*9880d681SAndroid Build Coastguard Worker 557*9880d681SAndroid Build Coastguard Worker.. _copyright-license-patents: 558*9880d681SAndroid Build Coastguard Worker 559*9880d681SAndroid Build Coastguard WorkerCopyright, License, and Patents 560*9880d681SAndroid Build Coastguard Worker=============================== 561*9880d681SAndroid Build Coastguard Worker 562*9880d681SAndroid Build Coastguard Worker.. note:: 563*9880d681SAndroid Build Coastguard Worker 564*9880d681SAndroid Build Coastguard Worker This section deals with legal matters but does not provide legal advice. We 565*9880d681SAndroid Build Coastguard Worker are not lawyers --- please seek legal counsel from an attorney. 566*9880d681SAndroid Build Coastguard Worker 567*9880d681SAndroid Build Coastguard WorkerThis section addresses the issues of copyright, license and patents for the LLVM 568*9880d681SAndroid Build Coastguard Workerproject. The copyright for the code is held by the individual contributors of 569*9880d681SAndroid Build Coastguard Workerthe code and the terms of its license to LLVM users and developers is the 570*9880d681SAndroid Build Coastguard Worker`University of Illinois/NCSA Open Source License 571*9880d681SAndroid Build Coastguard Worker<http://www.opensource.org/licenses/UoI-NCSA.php>`_ (with portions dual licensed 572*9880d681SAndroid Build Coastguard Workerunder the `MIT License <http://www.opensource.org/licenses/mit-license.php>`_, 573*9880d681SAndroid Build Coastguard Workersee below). As contributor to the LLVM project, you agree to allow any 574*9880d681SAndroid Build Coastguard Workercontributions to the project to licensed under these terms. 575*9880d681SAndroid Build Coastguard Worker 576*9880d681SAndroid Build Coastguard WorkerCopyright 577*9880d681SAndroid Build Coastguard Worker--------- 578*9880d681SAndroid Build Coastguard Worker 579*9880d681SAndroid Build Coastguard WorkerThe LLVM project does not require copyright assignments, which means that the 580*9880d681SAndroid Build Coastguard Workercopyright for the code in the project is held by its respective contributors who 581*9880d681SAndroid Build Coastguard Workerhave each agreed to release their contributed code under the terms of the `LLVM 582*9880d681SAndroid Build Coastguard WorkerLicense`_. 583*9880d681SAndroid Build Coastguard Worker 584*9880d681SAndroid Build Coastguard WorkerAn implication of this is that the LLVM license is unlikely to ever change: 585*9880d681SAndroid Build Coastguard Workerchanging it would require tracking down all the contributors to LLVM and getting 586*9880d681SAndroid Build Coastguard Workerthem to agree that a license change is acceptable for their contribution. Since 587*9880d681SAndroid Build Coastguard Workerthere are no plans to change the license, this is not a cause for concern. 588*9880d681SAndroid Build Coastguard Worker 589*9880d681SAndroid Build Coastguard WorkerAs a contributor to the project, this means that you (or your company) retain 590*9880d681SAndroid Build Coastguard Workerownership of the code you contribute, that it cannot be used in a way that 591*9880d681SAndroid Build Coastguard Workercontradicts the license (which is a liberal BSD-style license), and that the 592*9880d681SAndroid Build Coastguard Workerlicense for your contributions won't change without your approval in the 593*9880d681SAndroid Build Coastguard Workerfuture. 594*9880d681SAndroid Build Coastguard Worker 595*9880d681SAndroid Build Coastguard Worker.. _LLVM License: 596*9880d681SAndroid Build Coastguard Worker 597*9880d681SAndroid Build Coastguard WorkerLicense 598*9880d681SAndroid Build Coastguard Worker------- 599*9880d681SAndroid Build Coastguard Worker 600*9880d681SAndroid Build Coastguard WorkerWe intend to keep LLVM perpetually open source and to use a liberal open source 601*9880d681SAndroid Build Coastguard Workerlicense. **As a contributor to the project, you agree that any contributions be 602*9880d681SAndroid Build Coastguard Workerlicensed under the terms of the corresponding subproject.** All of the code in 603*9880d681SAndroid Build Coastguard WorkerLLVM is available under the `University of Illinois/NCSA Open Source License 604*9880d681SAndroid Build Coastguard Worker<http://www.opensource.org/licenses/UoI-NCSA.php>`_, which boils down to 605*9880d681SAndroid Build Coastguard Workerthis: 606*9880d681SAndroid Build Coastguard Worker 607*9880d681SAndroid Build Coastguard Worker* You can freely distribute LLVM. 608*9880d681SAndroid Build Coastguard Worker* You must retain the copyright notice if you redistribute LLVM. 609*9880d681SAndroid Build Coastguard Worker* Binaries derived from LLVM must reproduce the copyright notice (e.g. in an 610*9880d681SAndroid Build Coastguard Worker included readme file). 611*9880d681SAndroid Build Coastguard Worker* You can't use our names to promote your LLVM derived products. 612*9880d681SAndroid Build Coastguard Worker* There's no warranty on LLVM at all. 613*9880d681SAndroid Build Coastguard Worker 614*9880d681SAndroid Build Coastguard WorkerWe believe this fosters the widest adoption of LLVM because it **allows 615*9880d681SAndroid Build Coastguard Workercommercial products to be derived from LLVM** with few restrictions and without 616*9880d681SAndroid Build Coastguard Workera requirement for making any derived works also open source (i.e. LLVM's 617*9880d681SAndroid Build Coastguard Workerlicense is not a "copyleft" license like the GPL). We suggest that you read the 618*9880d681SAndroid Build Coastguard Worker`License <http://www.opensource.org/licenses/UoI-NCSA.php>`_ if further 619*9880d681SAndroid Build Coastguard Workerclarification is needed. 620*9880d681SAndroid Build Coastguard Worker 621*9880d681SAndroid Build Coastguard WorkerIn addition to the UIUC license, the runtime library components of LLVM 622*9880d681SAndroid Build Coastguard Worker(**compiler_rt, libc++, and libclc**) are also licensed under the `MIT License 623*9880d681SAndroid Build Coastguard Worker<http://www.opensource.org/licenses/mit-license.php>`_, which does not contain 624*9880d681SAndroid Build Coastguard Workerthe binary redistribution clause. As a user of these runtime libraries, it 625*9880d681SAndroid Build Coastguard Workermeans that you can choose to use the code under either license (and thus don't 626*9880d681SAndroid Build Coastguard Workerneed the binary redistribution clause), and as a contributor to the code that 627*9880d681SAndroid Build Coastguard Workeryou agree that any contributions to these libraries be licensed under both 628*9880d681SAndroid Build Coastguard Workerlicenses. We feel that this is important for runtime libraries, because they 629*9880d681SAndroid Build Coastguard Workerare implicitly linked into applications and therefore should not subject those 630*9880d681SAndroid Build Coastguard Workerapplications to the binary redistribution clause. This also means that it is ok 631*9880d681SAndroid Build Coastguard Workerto move code from (e.g.) libc++ to the LLVM core without concern, but that code 632*9880d681SAndroid Build Coastguard Workercannot be moved from the LLVM core to libc++ without the copyright owner's 633*9880d681SAndroid Build Coastguard Workerpermission. 634*9880d681SAndroid Build Coastguard Worker 635*9880d681SAndroid Build Coastguard WorkerNote that the LLVM Project does distribute dragonegg, **which is 636*9880d681SAndroid Build Coastguard WorkerGPL.** This means that anything "linked" into dragonegg must itself be compatible 637*9880d681SAndroid Build Coastguard Workerwith the GPL, and must be releasable under the terms of the GPL. This implies 638*9880d681SAndroid Build Coastguard Workerthat **any code linked into dragonegg and distributed to others may be subject to 639*9880d681SAndroid Build Coastguard Workerthe viral aspects of the GPL** (for example, a proprietary code generator linked 640*9880d681SAndroid Build Coastguard Workerinto dragonegg must be made available under the GPL). This is not a problem for 641*9880d681SAndroid Build Coastguard Workercode already distributed under a more liberal license (like the UIUC license), 642*9880d681SAndroid Build Coastguard Workerand GPL-containing subprojects are kept in separate SVN repositories whose 643*9880d681SAndroid Build Coastguard WorkerLICENSE.txt files specifically indicate that they contain GPL code. 644*9880d681SAndroid Build Coastguard Worker 645*9880d681SAndroid Build Coastguard WorkerWe have no plans to change the license of LLVM. If you have questions or 646*9880d681SAndroid Build Coastguard Workercomments about the license, please contact the `LLVM Developer's Mailing 647*9880d681SAndroid Build Coastguard WorkerList <mailto:[email protected]>`_. 648*9880d681SAndroid Build Coastguard Worker 649*9880d681SAndroid Build Coastguard WorkerPatents 650*9880d681SAndroid Build Coastguard Worker------- 651*9880d681SAndroid Build Coastguard Worker 652*9880d681SAndroid Build Coastguard WorkerTo the best of our knowledge, LLVM does not infringe on any patents (we have 653*9880d681SAndroid Build Coastguard Workeractually removed code from LLVM in the past that was found to infringe). Having 654*9880d681SAndroid Build Coastguard Workercode in LLVM that infringes on patents would violate an important goal of the 655*9880d681SAndroid Build Coastguard Workerproject by making it hard or impossible to reuse the code for arbitrary purposes 656*9880d681SAndroid Build Coastguard Worker(including commercial use). 657*9880d681SAndroid Build Coastguard Worker 658*9880d681SAndroid Build Coastguard WorkerWhen contributing code, we expect contributors to notify us of any potential for 659*9880d681SAndroid Build Coastguard Workerpatent-related trouble with their changes (including from third parties). If 660*9880d681SAndroid Build Coastguard Workeryou or your employer own the rights to a patent and would like to contribute 661*9880d681SAndroid Build Coastguard Workercode to LLVM that relies on it, we require that the copyright owner sign an 662*9880d681SAndroid Build Coastguard Workeragreement that allows any other user of LLVM to freely use your patent. Please 663*9880d681SAndroid Build Coastguard Workercontact the `LLVM Foundation Board of Directors <mailto:[email protected]>`_ for more 664*9880d681SAndroid Build Coastguard Workerdetails. 665