Gitiles
Code Review Sign In
gerrit-public.fairphone.software / fp2-dev / platform / external / llvm / 8d0ac6904db90f91a428a2aed95bf4cbc0278b9b / . / docs / DeveloperPolicy.html
blob: 9b971759cb9b004a61bdd903e7a4e3088ef4d5ae [file] [log] [blame]
Reid Spencer8d0ac692007-02-13 09:06:01 +0000[diff] [blame^]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
3<html>
4<head>
5 <title>LLVM Developer Policy</title>
6 <link rel="stylesheet" href="llvm.css" type="text/css">
7</head>
8<body>
9 <div class="doc_warning">DRAFT Only.</div>
10
11<div class="doc_title">LLVM Developer Policy</div>
12<table class="layout"><tr class="layout"><td class="layout">
13<h2>Contents</h2>
14<ol>
15 <li><a href="#overview">Overview</a></li>
16 <li><a href="#terms">Terminology</a></li>
17 <li><a href="#candl">Copyright and License</a>
18 <ol>
19 <li><a href="#copyright">Copyright</a></li>
20 <li><a href="#license">License</a></li>
21 <li><a href="#devagree">Developer Agreements</a></li>
22 </ol></li>
23 <li><a href="#general">General Policies</a>
24 <ol>
25 <li><a href="#informed">Stay Informed</a> </li>
26 <li><a href="#newwork">Starting New Work</a></li>
27 <li><a href="#reviews">Code Reviews</a></li>
28 <li><a href="#incremental">Incremental Development</a></li>
29 <li><a href="#quality">Quality</a></li>
30 <li><a href="#testcases">Test Cases</a></li>
31 </ol></li>
32 <li><a href="#patches">Patch Policies</a>
33 <ol>
34 <li><a href="#p_form">Patch Form</a></li>
35 <li><a href="#p_testing">Patch Testing</a></li>
36 <li><a href="#p_submission">Patch Submission</a></li>
37 <li><a href="#p_after">After Submission</a></li>
38 <li><a href="#c_access">Obtaining Commit Access</a></li>
39 <li><a href="#c_new">New Committers</a></li>
40 </ol></li>
41</ol>
42<div class="doc_author">Written by LLVM Oversight Team</div>
43</td><td class="layout">
44
45<!--=========================================================================-->
46<div class="doc_section"><a name="overview">Overview</a></div>
47<!--=========================================================================-->
48<div class="doc_text">
49 <p>This document contains the LLVM Developer Policy which defines the
50 project's policy towards developer's and their contributions. The intent of
51 this policy is to eliminate mis-communication, rework, and confusion that
52 might arise from the distributed nature of LLVM's development. By stating
53 the policy in clear terms, we hope each developer can know ahead of time
54 what to expect when making LLVM contributions.</p>
55</div>
56<!--=========================================================================-->
57<div class="doc_section"><a name="terms">Terminology</a></div>
58<!--=========================================================================-->
59<div class="doc_text">
60 <p>So that the policies defined in the next sections are clear, we first
61 define some terms here.</p>
62 <dl>
63 <dt><a name="t_change">Change</a></dt>
64 <dd>Any modification to LLVM including documentation, tests, build system,
65 etc. either in <a href="#t_patch">patch</a> or
66 <a href="#t_commit">commit</a> form.</dd>
67 <dt><a name="t_commit">Commit</a><dt>
68 <dd>A <a href="t_change">change</a> submitted directly to LLVM software
69 respository via the <tt>cvs commit</tt> command.</dd>
70 <dt><a name="t_developer">Developer</a></dt>
71 <dd>Anyone who submits a <a href="#t_change">change</a> to LLVM.</dd>
72 <dt><a name="t_inrement">Increment</a></dt>
73 <dd>A <a href="#t_change">change</a> or set of changes, whether by
74 <a href="#t_patch">patch</a> or <a href="#t_commit">commit</a>, that are
75 related by a single common purpose. Increments are atomic as they
76 leave LLVM in a stable state (both compiling and working properly).</dd>
77 <dt><a name="t_must">Must</a></dt>
78 <dd>When used in a policy statement, the term <i>must</i> implies a
79 non-optional requirement on the developer.</dd>
80 <dt><a name="t_patch">Patch</a></dt>
81 <dd>A <a href="#t_change">change</a> submitted by email in patch (diff)
82 format generated by the <tt>cvs diff</tt> command.</dd>
83 <dt><a name="t_should">Should</a></dt>
84 <dd>When used in a policy statement, the term <i>should</i> implies a
85 recommended but optional requirement on the developer.</dd>
86 </dl>
87</div>
88
89</td></tr></table>
90
91<!--=========================================================================-->
92<div class="doc_section"><a name="candl">Copyright and License</a></div>
93<!--=========================================================================-->
94<div class="doc_text">
95 <p>We address here the issues of copyright and license for the LLVM project.
96 A copyright is literally the "right to copy". It is a set of exclusive rights
97 granted to a party regulating the particular expression of information.
98 In this case, the information is LLVM. A license is something granted by a
99 copyright holder to other parties that controls the use of the information
100 by them. Currently, the University of Illinois is the LLVM copyright holder
101 and the terms of its license to LLVM users and developers is the
102 University of Illinois Open Source License (see LICENSE.txt).</p>
103</div>
104<!-- _______________________________________________________________________ -->
105<div class="doc_subsection"><a name="copyright">Copyright</a></div>
106<div class="doc_text">
107 <p>The LLVM project believes in correct attribution of contributions to
108 their contributors. Developers should, therefore, place their name at the
109 top of any source file they originate and list their contributions in the
110 CREDITS.TXT file. Furthermore, correct attribution of submitted patches
111 should be made in the commit comments.</p>
112 <p>However, for consistency and ease of management, the project requires the
113 copyright for all LLVM software to be held by a single copyright holder.
114 Although UIUC may assign the copyright of the software to another entity,
115 the intent for the project is to always have a single entity hold the copy
116 rights to LLVM at any given time.
117 <p>Having multiple copyright holders for various portions of LLVM is
118 problematic in the management of the software. Having a single copyright
119 holder is in the best interests of all developers and users as it greatly
120 reduces the managerial burden for any kind of administrative or technical
121 decisions about LLVM.</p>
122</div>
123<!-- _______________________________________________________________________ -->
124<div class="doc_subsection"><a name="license">License</a></div>
125<div class="doc_text">
126 <p>LLVM licensing decisions will be made by the LLVM Oversight Group. Any
127 issues, comments or suggestions with the licensing should be sent to
128 <a href="mailto:oversight@llvm.org">oversight@llvm.org</a>.</p>
129 <p>The LLVM Oversight Group intends to keep LLVM perpetually open source
130 and to use liberal open source licenses. The current license is the
131 University of Illinois Open Source License (see LICENSE.TXT), which boils
132 down to this:</p>
133 <ul>
134 <li>You can freely distribute LLVM.</li>
135 <li>You must retain the copyright notice if you redistribute.</li>
136 <li>Binaries derived from LLVM must reproduce the copyright notice.</li>
137 <li>You can't use our names to promote your LLVM derived products.</li>
138 <li>There's no warranty on LLVM at all.</li>
139 </ul>
140 <p>We believe this fosters the widest adoption of LLVM because it allows
141 commercial products to be derived from LLVM with few restrictions and
142 without a requirement for making any derived works also open source. The
143 intent of the license is to let people use LLVM freely with only the
144 obligation to be honest about where it came from.</p>
145</div>
146<!-- _______________________________________________________________________ -->
147<div class="doc_subsection"><a name="devagree">Developer Agreements</a></div>
148<div class="doc_text">
149 <p>With regards to the LLVM copyright and licensing, developer's agree to:</p>
150 <ul>
151 <li>give up their copy rights to any contribution made so that the entire
152 software base can be managed by a single copyright holder.</li>
153 <li>allow their contribution(s) to be licensed as open source by the then
154 current or subsequent license chosen by the LLVM Oversight Group.</li>
155 <li>not make LLVM available under any other licensing agreement.</li>
156 </ul>
157</div>
158
159<!--=========================================================================-->
160<div class="doc_section"><a name="general">General Policies</a></div>
161<!--=========================================================================-->
162<div class="doc_text">
163 <p>This section contains policies that pertain generally to LLVM developers.
164 <p>LLVM Developers are expected to meet the following obligations in order
165 for LLVM to maintain a high standard of quality<p>
166</div>
167
168<!-- _______________________________________________________________________ -->
169<div class="doc_subsection"> <a name="informed">Stay Informed</a> </div>
170<div class="doc_text">
171 <p>Developers should stay informed by reading at least the
172 <a href="mailto:llvmdev@llvm.org">llvmdev</a> email list. If you are doing
173 anything more than just casual work on LLVM, it is highly suggested that you
174 also subscribe to the llvm-commits list and pay attention to changes being
175 made by others.</p>
176 <p>Active developers must register an email account with bugzilla
177 (<a href="http://llvm.org/bugs/">http://llvm.org/bugs/</a>) and preferably
178 subscribe to the llvm-bugs email list to keep track of bugs occuring in
179 LLVM.</p>
180</div>
181
182<!-- _______________________________________________________________________ -->
183<div class="doc_subsection"> <a name="newwork">Starting New Work</a></div>
184<div class="doc_text">
185 <p>When a developer begins new work with the aim of contributing it back to
186 LLVM, s/he must inform the community with an email to llvm-dev email list,
187 to the extent possible. The reason for this is to:
188 <ul>
189 <li>keep the community informed about future changes to LLVM, </li>
190 <li>avoid duplication of effort by having multiple parties working on the
191 same thing and not knowing about it, and</li>
192 <li>ensure that any issues around the proposed work are discussed and
193 resolved before any significant work is accomplished.</li>
194 </ul>
195</div>
196
197<!-- _______________________________________________________________________ -->
198<div class="doc_subsection"> <a name="reviews">Code Reviews</a></div>
199<div class="doc_text">
200 <p>LLVM has a code review policy. Code review is an excellent way to ensure
201 high quality in the software. The following policies apply:</p>
202 <ol>
203 <li>All developers are required to have any significant changes reviewed
204 before they are committed to the repository.</li>
205 <li>Code reviews are conducted by email.</li>
206 <li>Code can be reviewed either before it is committed or after.</li>
207 <li>The developer responsible for a code change is also responsible for
208 making all necessary review changes.</li>
209 <li>Developers should participate in code reviews as both a reviewer and
210 a reviewee. We don't have a dedicated team of reviewers. If someone is
211 kind enough to review your code, you should return the favor for someone
212 else.</li>
213 </ol>
214</div>
215
216<!-- _______________________________________________________________________ -->
217<div class="doc_subsection"> <a name="incremental">Incremental Development</a>
218</div>
219<div class="doc_text">
220 <p>LLVM uses an incremental development style and all developers are expected
221 to follow this practice. Incremental development is a big key to LLVM's
222 success and it is essential that developers submit incremental patches. The
223 following defines the incremental development approach:</p>
224 <ol>
225 <li>The first task is to define the increment and get consensus (with the
226 LLVM development community) on what the end goal of the change is. Making
227 random small changes that go nowhere is not useful for anyone.</li>
228 <li>An increment is the smallest patch size necessary to effect one change
229 in LLVM.</li>
230 <li>Increments can be stand alone (e.g. to fix a bug), or part of a planned
231 series of increments towards some development goal.</li>
232 <li>Increments should be kept as small as possible. This simplifies your
233 work (into a logical progression), simplifies code review and reduces the
234 chance that you will get negative feedback on the change. Small increments
235 also facilitate the maintenance of a high quality code base.</li>
236 </ol>
237</div>
238
239<!-- _______________________________________________________________________ -->
240<div class="doc_subsection"> <a name="quality">Quality</a></div>
241<div class="doc_text">
242 <p>The minimum quality standards for any change to the main development
243 branch are:</p>
244 <ol>
245 <li>Code must adhere to the
246 <a href="CodingStandards.html">LLVM Coding Standards</a>.</li>
247 <li>Code must compile cleanly (no errors, no warnings) on at least one
248 platform.</li>
249 <li>Code must pass the deja gnu (llvm/test) test suite.</li>
250 <li>
251 </ol>
252 <p>Additionally, the committer is responsible for all of the following items.
253 It is considered significantly preferable for all of these items to be
254 accounted for <i>before</i> the code is submitted for review or committed.</p>
255 <ol>
256 <li>Code must compile cleanly on all platforms.</li>
257 <li>Code must pass the <tt>llvm-test</tt> test suite including
258 SPEC CINT2000, SPEC CFP2000, SPEC CINT2006, and SPEC CFP2006.</li>
259 <li>The changesat must not cause performance or correctness regressions
260 for the LLVM tools.</li>
261 <li>The changes must not cause performance or correctness regressions in
262 code compiled with LLVM on all applicable targets.</li>
263 </ol>
264</div>
265
266<!-- _______________________________________________________________________ -->
267<div class="doc_subsection"> <a name="testcases">Test Cases</a></div>
268<div class="doc_text">
269 <p>Developers are required to create test cases for regressions and new
270 features and include them with their changes. The following policies
271 apply:</p>
272 <ol>
273 <li>All feature and regression test cases must be added to the
274 <tt>llvm/test</tt> directory. The appropriate subdirectory should be
275 selected (see the <a href="TestingGuide.html">Testing Guide</a> for
276 details.</li>
277 <li>Test cases should be written in LLVM assembly language unless the
278 feature or regression being tested requires another language.</li>
279 <li>Test cases, especially for regressions, should be as reduced as
280 possible, preferably by
281 <a href=CommandGuide/html/bugpoint.html>bugpoint</a>. It is unacceptable
282 to place an entire failing program into <tt>llvm/test</tt> as this creates
283 a <i>time-to-test</i> burden on all developers. Keep them short!</li>
284 <li>More extensive test cases (applications, benchmarks, etc.) should be
285 added to the <tt>llvm-test</tt> test suite, after approval from the
286 Oversight Group. This test suite is for coverage not features or
287 regressions.</li>
288 </ol>
289</div>
290
291<!--=========================================================================-->
292<div class="doc_section"><a name="patches">Patch Policies</a></div>
293<!--=========================================================================-->
294<div class="doc_text">
295 <p>This section contains policies that pertain to submitting patches
296 to LLVM and committing code to the repository</p>
297</div>
298<!-- _______________________________________________________________________ -->
299<div class="doc_subsection"> <a name="p_form">Patch Form</a></div>
300<div class="doc_text">
301 <p>When submitting a patch, developers must follow these rules:</p>
302 <ol>
303 <li>Patches must be made against the CVS HEAD (main development trunk),
304 not a branch.</li>
305 <li>Patches must be made with this cvs command:<pre>
306 cvs diff -Ntdup -5</pre> or with the utility <tt>utils/mkpatch</tt>.</li>
307 <li>Patches must not include differences in generated code such as the
308 code generated by <tt>flex</tt>, <tt>bison</tt> or <tt>tblgen</tt>. The
309 <tt>utils/mkpatch</tt> utility takes care of this for you.</li>
310 </ol>
311</div>
312<!-- _______________________________________________________________________ -->
313<div class="doc_subsection"> <a name="p_testing">Patch Testing</a></div>
314<div class="doc_text">
315 <p>Before a patch is submitted for review, it should be tested to ensure
316 that:</p>
317 <ol>
318 <li>The patch must compile against the CVS HEAD cleanly (zero warnings, zero
319 errors).</li>
320 <li>All the llvm/test (Deja Gnu) tests must pass.</li>
321 <li>All the llvm-test tests must pass on at least one platform.</li>
322 </ol>
323</div>
324<!-- _______________________________________________________________________ -->
325<div class="doc_subsection"> <a name="p_submission">Patch Submission</a></div>
326<div class="doc_text">
327 <p>When a patch is ready to be submitted, these policies apply:</p>
328 <ol>
329 <li>Patches should be submitted immediately after they are generated. Stale
330 patches are unlikely to apply correctly and could be rejected simply due to
331 age.</li>
332 <li>Patches must be submitted by e-mail to the
333 <a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits">
334 llvm-commits</a> list.</li>
335 </ol>
336</div>
337
338<!-- _______________________________________________________________________ -->
339<div class="doc_subsection"> <a name="p_after">After Submission</a></div>
340<div class="doc_text">
341 <p>After a patch has been submitted, these policies apply:</p>
342 <ol>
343 <li>The patch is subject to review by anyone on the llvm-commits email list.
344 </li>
345 <li>Any changes recommended by the reviewer must be made by the submitter
346 of the patch and the patch re-submitted.</li>
347 <li>If the submitter believes the review comment is in error, a response to
348 the <a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits">
349 llvm-commits</a> list should be made explaining why the recommendation
350 cannot be followed.</li>
351 </ol>
352</div>
353
354<!-- _______________________________________________________________________ -->
355<div class="doc_subsection"> <a name="p_after">After Commit</a></div>
356<div class="doc_text">
357 <p>After a patch has been committed, these policies apply:</p>
358 <ol>
359 <li>The patch is subject to further review by anyone on the llvm-commits
360 email list.</li>
361 <li>The patch submitter is responsible for all aspects of the patch per
362 the <a href="quality">quality policy</a> above.</li>
363 <li>If the patch is discovered to not meet the
364 <a href="quality">quality standards</a> standards within a reasonable time
365 frame (24 hours), it may be subject to reversal.</li>
366 </ol>
367</div>
368
369<!-- _______________________________________________________________________ -->
370<div class="doc_subsection"> <a name="c_access">Gaining Commit Access</a></div>
371<div class="doc_text">
372 <p>Commit access to the repository is granted according to this policy:</p>
373 <ol>
374 <li>Commit access is not granted to anyone unless they specifically ask for
375 it.</li>
376 <li>Requests for commit access must be sent to the LLVM Oversight Group at
377 <a href="mailto:oversight@llvm.org">oversight@llvm.org</a>.</li>
378 <li>Granting commit access is at the sole discretion of the LLVM Oversight
379 Group.</li>
380 <li>Submitting patches to LLVM via the patch policy above will greatly
381 increase the chance that your request for commit access is granted.</li>
382 <li>Getting to know the members of the LLVM community (email, IRC, in person
383 contact, etc.) will also increase your chances.</li>
384 </ol>
385</div>
386
387<!-- _______________________________________________________________________ -->
388<div class="doc_subsection"> <a name="c_new">New Committers</a></div>
389<div class="doc_text">
390 <p>For those who have recently obtained commit access, the following policies
391 apply:</p>
392 <ol>
393 <li>You are granted <i>commit-after-approval</i> to all parts of LLVM.
394 To get approval, submit a patch to llvm-commits per the patch policies
395 above. When approved you may commit it yourself.</li>
396 <li>You are granted <i>commit-without-approavl</i> to those portions of LLVM
397 that you own (contributed) or maintain (have been assigned responsibility
398 for), with the proviso that such commits must not break the build. This is
399 a "trust but verify" policy and commits of this nature are reviewed after
400 they are committed.</li>
401 <li>Commits that violate the <a href="quality">quality standards</a> may
402 be reverted. This is necessary when the change blocks other developers from
403 making progress. The developers is welcome to re-commit the change after
404 the problem has been fixed.</li>
405 <li>Multiple violations of these policies or a single aggregious violation
406 may cause commit access to be revoked, at the sole discretion of the
407 LLVM Oversight Group.</li>
408 </ol>
409</div>
410
411<!--=========================================================================-->
412<div class="doc_section"><a name="notes">Policy Notes</a></div>
413<!--=========================================================================-->
414<div class="doc_text">
415 <p>This section contains some notes on policy topics that need to be
416 resolved and incorporated into the main body of the document above.</p>
417 <ol>
418 <li>When to open a new bug and when to re-use an existing one. For example
419 PR1158. If the same assertion happens do you open a new bug or reopen
420 1158?</li>
421 </ol>
422</div>
423
424<!-- *********************************************************************** -->
425<hr>
426<address>
427 <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
428 src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
429 <a href="http://validator.w3.org/check/referer"><img
430 src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!" /></a>
431 Written By: <a href="mailto:oversight@llvm.org">LLVM Oversight Group</a><br>
432 <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br>
433 Last modified: $Date$
434</address>
435</body>
436</html>