1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
|
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>LLVM Community Support Policy — LLVM 13 documentation</title>
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
<script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/doctools.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Sphinx Quickstart Template" href="SphinxQuickstartTemplate.html" />
<link rel="prev" title="LLVM Code-Review Policy and Practices" href="CodeReview.html" />
<style type="text/css">
table.right { float: right; margin-left: 20px; }
table.right td { border: 1px solid #ccc; }
</style>
</head><body>
<div class="logo">
<a href="index.html">
<img src="_static/logo.png"
alt="LLVM Logo" width="250" height="88"/></a>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="SphinxQuickstartTemplate.html" title="Sphinx Quickstart Template"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="CodeReview.html" title="LLVM Code-Review Policy and Practices"
accesskey="P">previous</a> |</li>
<li><a href="https://llvm.org/">LLVM Home</a> | </li>
<li><a href="index.html">Documentation</a>»</li>
<li class="nav-item nav-item-1"><a href="GettingInvolved.html" accesskey="U">Getting Involved</a> »</li>
<li class="nav-item nav-item-this"><a href="">LLVM Community Support Policy</a></li>
</ul>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3>Documentation</h3>
<ul class="want-points">
<li><a href="https://llvm.org/docs/GettingStartedTutorials.html">Getting Started/Tutorials</a></li>
<li><a href="https://llvm.org/docs/UserGuides.html">User Guides</a></li>
<li><a href="https://llvm.org/docs/Reference.html">Reference</a></li>
</ul>
<h3>Getting Involved</h3>
<ul class="want-points">
<li><a href="https://llvm.org/docs/Contributing.html">Contributing to LLVM</a></li>
<li><a href="https://llvm.org/docs/HowToSubmitABug.html">Submitting Bug Reports</a></li>
<li><a href="https://llvm.org/docs/GettingInvolved.html#mailing-lists">Mailing Lists</a></li>
<li><a href="https://llvm.org/docs/GettingInvolved.html#irc">IRC</a></li>
<li><a href="https://llvm.org/docs/GettingInvolved.html#meetups-and-social-events">Meetups and Social Events</a></li>
</ul>
<h3>Additional Links</h3>
<ul class="want-points">
<li><a href="https://llvm.org/docs/FAQ.html">FAQ</a></li>
<li><a href="https://llvm.org/docs/Lexicon.html">Glossary</a></li>
<li><a href="https://llvm.org/pubs">Publications</a></li>
<li><a href="https://github.com/llvm/llvm-project//">Github Repository</a></li>
</ul>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/SupportPolicy.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="llvm-community-support-policy">
<h1>LLVM Community Support Policy<a class="headerlink" href="#llvm-community-support-policy" title="Permalink to this headline">¶</a></h1>
<p>As a compilation infrastructure, LLVM has multiple types of users, both
downstream and upstream, of many combinations of its projects, tools and
libraries.</p>
<p>There is a core part of it that encompass the implementation of the compiler
(front/middle/back ends), run-time libraries (RT, C++, OpenMP, etc) and
associated tools (debugger, linker, object file manipulation, etc). These
components are present in the public release on our supported architectures
and operating systems and the whole community must maintain and care about.</p>
<p>There are, however, other components within the main repository that either
cater to a specific sub-community of LLVM (upstream or downstream) or
help parts of the community to integrate LLVM into their own development tools
or external projects. Those parts of the main repository don’t always have
rigorous testing like the core parts, nor are they validated and shipped with
our public upstream releases.</p>
<p>Even not being a core part of the project, we have enough sub-communities
needing those changes with enough overlap that having them in the main
repository is beneficial to minimise the repetition of those changes in all
the external repositories that need them.</p>
<p>But the maintenance costs of such diverse ecosystem is non trivial, so we divide
the level of support in two tiers: core and peripheral, with two
different levels of impact and responsibilities. Those tiers refer only to the
main repository (<code class="docutils literal notranslate"><span class="pre">llvm-project</span></code>) and not the other repositories in our git
project, unless explicitly stated.</p>
<p>Regardless of the tier, all code must follow the existing policies on quality,
reviews, style, etc.</p>
<div class="section" id="core-tier">
<h2>Core Tier<a class="headerlink" href="#core-tier" title="Permalink to this headline">¶</a></h2>
<p>The core tier encompasses all of the code in the main repository that is
in production, is actively tested and released in a regular schedule, including
core LLVM APIs and infrastructure, front/middle/back-ends, run-time libraries,
tools, etc.</p>
<p>It is the responsibility of <strong>every</strong> LLVM developer to care for the core tier
regardless of where their work is applied to.</p>
<div class="section" id="what-is-covered">
<h3>What is covered<a class="headerlink" href="#what-is-covered" title="Permalink to this headline">¶</a></h3>
<dl class="simple">
<dt>The core tier is composed of:</dt><dd><ul class="simple">
<li><p>Core code (<code class="docutils literal notranslate"><span class="pre">llvm-project</span></code>) present in official releases and buildbots:
compiler, debugger, linker, libraries, etc, including infrastructure code
(table-gen, lit, file-check, unit-tests, etc).</p></li>
<li><p>Build infrastructure that creates releases and buildbots (CMake, scripts).</p></li>
<li><p><a class="reference external" href="https://github.com/llvm/phabricator">Phabricator</a> and
<a class="reference external" href="https://github.com/llvm/llvm-zorg">buildbot</a> infrastructure.</p></li>
<li><p>The <a class="reference external" href="https://github.com/llvm/llvm-test-suite">test-suite</a>.</p></li>
</ul>
</dd>
</dl>
</div>
<div class="section" id="requirements">
<h3>Requirements<a class="headerlink" href="#requirements" title="Permalink to this headline">¶</a></h3>
<dl class="simple">
<dt>Code in this tier must:</dt><dd><ul class="simple">
<li><p>Keep official buildbots green, with warnings on breakages being emailed to
all affected developers. Those must be fixed as soon as possible or patches
must be reverted, as per review policy.</p></li>
<li><p>Bit-rot of a component in the core tier will result in that component being
downgraded to the peripheral tier or being removed. Sub-communities can
avoid this by fixing all raised issues in a timely manner.</p></li>
</ul>
</dd>
</dl>
</div>
</div>
<div class="section" id="peripheral-tier">
<h2>Peripheral Tier<a class="headerlink" href="#peripheral-tier" title="Permalink to this headline">¶</a></h2>
<p>The peripheral tier encompass the parts of LLVM that cater to a specific
sub-community and which don’t usually affect the core components directly.</p>
<p>This includes experimental back-ends, disabled-by-default options and
alternative paths (work-in-progress replacements) in the same repository, as
well as separate efforts to integrate LLVM development with local practices.</p>
<p>It is the responsibility of each sub-community to care about their own parts
and the intersection of that with the core tier and other peripheral parts.</p>
<dl class="simple">
<dt>There are three main groups of code that fit in this category:</dt><dd><ul class="simple">
<li><p>Code that is making its way into LLVM, via the <a class="reference external" href="https://llvm.org/docs/DeveloperPolicy.html#introducing-new-components-into-llvm">experimental</a>
roadmap or similar efforts.</p></li>
<li><p>Code that is making its way out of LLVM, via deprecation, replacement or
bit-rot, and will be removed if the sub-community that cares about it
cannot maintain it.</p></li>
<li><p>Code that isn’t meant to be in LLVM core and can coexist with the code in
the core tier (and others in the peripheral tier) long term, without causing
breakages or disturbances.</p></li>
</ul>
</dd>
</dl>
<div class="section" id="id1">
<h3>What is covered<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h3>
<dl class="simple">
<dt>The peripheral tier is composed of:</dt><dd><ul class="simple">
<li><p>Experimental targets and options that haven’t been enable by default yet.</p></li>
<li><p>Main repository projects that don’t get released or regularly tested.</p></li>
<li><p>Legacy tools and scripts that aren’t used in upstream validation.</p></li>
<li><p>Alternative build systems (ex. GN, Bazel) and related infrastructure.</p></li>
<li><p>Tools support (ex. gdb scripts, editor configuration, helper scripts).</p></li>
</ul>
</dd>
</dl>
</div>
<div class="section" id="id2">
<h3>Requirements<a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h3>
<dl class="simple">
<dt>Code in this tier must:</dt><dd><ul class="simple">
<li><p>Have a clear benefit for residing in the main repository, catering to an
active sub-community (upstream or downstream).</p></li>
<li><p>Be actively maintained by such sub-community and have its problems addressed
in a timely manner.</p></li>
</ul>
</dd>
<dt>Code in this tier must <strong>not</strong>:</dt><dd><ul class="simple">
<li><p>Break or invalidate core tier code or infrastructure. If that happens
accidentally, reverting functionality and working on the issues offline
is the only acceptable course of action.</p></li>
<li><p>Negatively affect development of core tier code, with the sub-community
involved responsible for making changes to address specific concerns.</p></li>
<li><p>Negatively affect other peripheral tier code, with the sub-communities
involved tasked to resolve the issues, still making sure the solution doesn’t
break or invalidate the core tier.</p></li>
<li><p>Impose sub-optimal implementation strategies on core tier components as a
result of idiosyncrasies in the peripheral component.</p></li>
<li><p>Have build infrastructure that spams all developers about their breakages.</p></li>
<li><p>Fall into disrepair. This is a reflection of lack of an active sub-community
and will result in removal.</p></li>
</ul>
</dd>
<dt>Code in this tier should:</dt><dd><ul class="simple">
<li><p>Have infrastructure to test, whenever meaningful, with either no warnings or
notification contained within the sub-community.</p></li>
<li><p>Have support and testing that scales with the complexity and resilience of
the component, with the bar for simple and gracefully-degrading components
(such as editor bindings) much lower than for complex components that must
remain fresh with HEAD (such as experimental back-ends or alternative build
systems).</p></li>
<li><p>Have a document making clear the status of implementation, level of support
available, who the sub-community is and, if applicable, roadmap for inclusion
into the core tier.</p></li>
<li><p>Be restricted to a specific directory or have a consistent pattern (ex.
unique file suffix), making it easy to remove when necessary.</p></li>
</ul>
</dd>
</dl>
</div>
</div>
<div class="section" id="inclusion-policy">
<h2>Inclusion Policy<a class="headerlink" href="#inclusion-policy" title="Permalink to this headline">¶</a></h2>
<p>To add a new peripheral component, send an RFC to the appropriate dev list
proposing its addition and explaining how it will meet the support requirements
listed above. Different types of components could require different levels of
detail. when in doubt, ask the community what’s the best approach.</p>
<p>Inclusion must reach consensus in the RFC by the community and the approval of
the corresponding review (by multiple members of the community) is the official
note of acceptance.</p>
<p>After merge, there often is a period of transition, where teething issues on
existing buildbots are discovered and fixed. If those cannot be fixed straight
away, the sub-community is responsible for tracking and reverting all the
pertinent patches and retrying the inclusion review.</p>
<p>Once the component is stable in tree, it must follow this policy and the
deprecation rules below apply.</p>
<p>Due to the uncertain nature of inclusion, it’s advisable that new components
are not added too close to a release branch. The time will depend on the size
and complexity of the component, so adding release and testing managers on the
RFC and review is strongly advisable.</p>
</div>
<div class="section" id="deprecation-policy">
<h2>Deprecation Policy<a class="headerlink" href="#deprecation-policy" title="Permalink to this headline">¶</a></h2>
<p>The LLVM code base has a number of files that aren’t being actively maintained.
But not all of those files are obstructing the development of the project and
so it remains in the repository with the assumption that it could still be
useful for downstream users.</p>
<p>For code to remain in the repository, its presence must not impose an undue
burden on maintaining other components (core or peripheral).</p>
<div class="section" id="warnings">
<h3>Warnings<a class="headerlink" href="#warnings" title="Permalink to this headline">¶</a></h3>
<p>There are multiple types of issues that might trigger a request for deprecation,
including (but not limited to):</p>
<blockquote>
<div><ul class="simple">
<li><p>Changes in a component consistently break other areas of the project.</p></li>
<li><p>Components go broken for long periods of time (weeks or more).</p></li>
<li><p>Clearly superior alternatives are in use and maintenance is painful.</p></li>
<li><p>Builds and tests are harder / take longer, increasing the cost of
maintenance, overtaking the perceived benefits.</p></li>
</ul>
</div></blockquote>
<p>If the maintenance cost is higher than it is acceptable by the majority of
developers, it means that either the sub-community is too small (and the extra
cost should be paid locally), or not active enough (and the problems won’t be
fixed any time soon). In either case, removal of such problematic component is
justified.</p>
</div>
<div class="section" id="steps-for-removal">
<h3>Steps for removal<a class="headerlink" href="#steps-for-removal" title="Permalink to this headline">¶</a></h3>
<p>However clear the needs for removal are, we should take an incremental approach
to deprecating code, especially when there’s still a sub-community that cares
about it. In that sense, code will never be removed outright without a series
of steps are taken.</p>
<dl class="simple">
<dt>A minimum set of steps should be:</dt><dd><ol class="arabic simple">
<li><p>A proposal for removal / deactivation should be made to the developers’
mailing lists (<code class="docutils literal notranslate"><span class="pre">llvm-dev</span></code>, <code class="docutils literal notranslate"><span class="pre">cfe-dev</span></code>, <code class="docutils literal notranslate"><span class="pre">lldb-dev</span></code>, etc), with a clear
statement of the maintenance costs imposed and the alternatives, if
applicable.</p></li>
<li><p>There must be enough consensus on the list that removal is warranted, and no
pending proposals to fix the situation from a sub-community.</p></li>
<li><p>An announcement for removal must be made on the same lists, with ample time
for downstream users to take action on their local infrastructure. The time
will depend on what is being removed.</p>
<ol class="arabic simple">
<li><p>If a script or documents are to be removed, they can always be pulled
from previous revision, and can be removed within days.</p></li>
<li><p>if a whole target is removed, we need to first announce publicly, and
potentially mark as deprecated in one release, only to remove on the
next release.</p></li>
<li><p>Everything else will fall in between those two extremes.</p></li>
</ol>
</li>
<li><p>The removal is made by either the proposer or the sub-community that used to
maintain it, with replacements and arrangements made atomically on the same
commit.</p></li>
</ol>
</dd>
</dl>
<p>If a proposal for removal is delayed by the promise a sub-community will take
care of the code affected, the sub-community will have a time to fix all the
issues (depending on each case, as above), and if those are not fixed in time, a
subsequent request for removal should be made and the community may elect to
eject the component without further attempts to fix.</p>
</div>
<div class="section" id="reinstatement">
<h3>Reinstatement<a class="headerlink" href="#reinstatement" title="Permalink to this headline">¶</a></h3>
<p>If a component is removed from LLVM, it may, at a later date, request inclusion
of a modified version, with evidence that all of the issues were fixed and that
there is a clear sub-community that will maintain it.</p>
<p>By consequence, the pressure on such sub-community will be higher to keep
overall maintenance costs to a minimum and will need to show steps to mitigate
all of the issues that were listed as reasons for its original removal.</p>
<p>Failing on those again, will lead to become a candidate for removal yet again.</p>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="SphinxQuickstartTemplate.html" title="Sphinx Quickstart Template"
>next</a> |</li>
<li class="right" >
<a href="CodeReview.html" title="LLVM Code-Review Policy and Practices"
>previous</a> |</li>
<li><a href="https://llvm.org/">LLVM Home</a> | </li>
<li><a href="index.html">Documentation</a>»</li>
<li class="nav-item nav-item-1"><a href="GettingInvolved.html" >Getting Involved</a> »</li>
<li class="nav-item nav-item-this"><a href="">LLVM Community Support Policy</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2003-2021, LLVM Project.
Last updated on 2021-09-18.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.5.4.
</div>
</body>
</html>
|
