xref: /aosp_15_r20/external/llvm/docs/DeveloperPolicy.rst (revision 9880d6810fe72a1726cb53787c6711e909410d58)
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