llvm/docs/SupportPolicy.rst

   1 =============================
   2 LLVM Community Support Policy
   3 =============================
   4
   5 As a compilation infrastructure, LLVM has multiple types of users, both
   6 downstream and upstream, of many combinations of its projects, tools and
   7 libraries.
   8
   9 There is a core part of it that encompass the implementation of the compiler
  10 (front/middle/back ends), run-time libraries (RT, C++, OpenMP, etc) and
  11 associated tools (debugger, linker, object file manipulation, etc). These
  12 components are present in the public release on our supported architectures
  13 and operating systems and the whole community must maintain and care about.
  14
  15 There are, however, other components within the main repository that either
  16 cater to a specific sub-community of LLVM (upstream or downstream) or
  17 help parts of the community to integrate LLVM into their own development tools
  18 or external projects. Those parts of the main repository don't always have
  19 rigorous testing like the core parts, nor are they validated and shipped with
  20 our public upstream releases.
  21
  22 Even not being a core part of the project, we have enough sub-communities
  23 needing those changes with enough overlap that having them in the main
  24 repository is beneficial to minimise the repetition of those changes in all
  25 the external repositories that need them.
  26
  27 But the maintenance costs of such diverse ecosystem is non trivial, so we divide
  28 the level of support in two tiers: core and peripheral, with two
  29 different levels of impact and responsibilities. Those tiers refer only to the
  30 main repository (``llvm-project``) and not the other repositories in our git
  31 project, unless explicitly stated.
  32
  33 Regardless of the tier, all code must follow the existing policies on quality,
  34 reviews, style, etc.
  35
  36 Core Tier
  37 =========
  38
  39 The core tier encompasses all of the code in the main repository that is
  40 in production, is actively tested and released in a regular schedule, including
  41 core LLVM APIs and infrastructure, front/middle/back-ends, run-time libraries,
  42 tools, etc.
  43
  44 It is the responsibility of **every** LLVM developer to care for the core tier
  45 regardless of where their work is applied to.
  46
  47 What is covered
  48 ---------------
  49
  50 The core tier is composed of:
  51  * Core code (``llvm-project``) present in official releases and buildbots:
  52    compiler, debugger, linker, libraries, etc, including infrastructure code
  53    (table-gen, lit, file-check, unit-tests, etc).
  54  * Build infrastructure that creates releases and buildbots (CMake, scripts).
  55  * `Phabricator <https://github.com/llvm/phabricator>`_ and
  56    `buildbot <https://github.com/llvm/llvm-zorg>`_ infrastructure.
  57  * The `test-suite <https://github.com/llvm/llvm-test-suite>`_.
  58
  59 Requirements
  60 ------------
  61
  62 Code in this tier must:
  63  * Keep official buildbots green, with warnings on breakages being emailed to
  64    all affected developers. Those must be fixed as soon as possible or patches
  65    must be reverted, as per review policy.
  66  * Bit-rot of a component in the core tier will result in that component being
  67    downgraded to the peripheral tier or being removed. Sub-communities can
  68    avoid this by fixing all raised issues in a timely manner.
  69
  70 Peripheral Tier
  71 ===============
  72
  73 The peripheral tier encompass the parts of LLVM that cater to a specific
  74 sub-community and which don't usually affect the core components directly.
  75
  76 This includes experimental back-ends, disabled-by-default options and
  77 alternative paths (work-in-progress replacements) in the same repository, as
  78 well as separate efforts to integrate LLVM development with local practices.
  79
  80 It is the responsibility of each sub-community to care about their own parts
  81 and the intersection of that with the core tier and other peripheral parts.
  82
  83 There are three main groups of code that fit in this category:
  84  * Code that is making its way into LLVM, via the `experimental <https://llvm.org/docs/DeveloperPolicy.html#introducing-new-components-into-llvm>`_
  85    roadmap or similar efforts.
  86  * Code that is making its way out of LLVM, via deprecation, replacement or
  87    bit-rot, and will be removed if the sub-community that cares about it
  88    cannot maintain it.
  89  * Code that isn't meant to be in LLVM core and can coexist with the code in
  90    the core tier (and others in the peripheral tier) long term, without causing
  91    breakages or disturbances.
  92
  93 What is covered
  94 ---------------
  95
  96 The peripheral tier is composed of:
  97  * Experimental targets and options that haven't been enable by default yet.
  98  * Main repository projects that don't get released or regularly tested.
  99  * Legacy tools and scripts that aren't used in upstream validation.
 100  * Alternative build systems (ex. GN, Bazel) and related infrastructure.
 101  * Tools support (ex. gdb scripts, editor configuration, helper scripts).
 102
 103 Requirements
 104 ------------
 105
 106 Code in this tier must:
 107  * Have a clear benefit for residing in the main repository, catering to an
 108    active sub-community (upstream or downstream).
 109  * Be actively maintained by such sub-community and have its problems addressed
 110    in a timely manner.
 111
 112 Code in this tier must **not**:
 113  * Break or invalidate core tier code or infrastructure. If that happens
 114    accidentally, reverting functionality and working on the issues offline
 115    is the only acceptable course of action.
 116  * Negatively affect development of core tier code, with the sub-community
 117    involved responsible for making changes to address specific concerns.
 118  * Negatively affect other peripheral tier code, with the sub-communities
 119    involved tasked to resolve the issues, still making sure the solution doesn't
 120    break or invalidate the core tier.
 121  * Impose sub-optimal implementation strategies on core tier components as a
 122    result of idiosyncrasies in the peripheral component.
 123  * Have build infrastructure that spams all developers about their breakages.
 124  * Fall into disrepair. This is a reflection of lack of an active sub-community
 125    and will result in removal.
 126
 127 Code in this tier should:
 128  * Have infrastructure to test, whenever meaningful, with either no warnings or
 129    notification contained within the sub-community.
 130  * Have support and testing that scales with the complexity and resilience of
 131    the component, with the bar for simple and gracefully-degrading components
 132    (such as editor bindings) much lower than for complex components that must
 133    remain fresh with HEAD (such as experimental back-ends or alternative build
 134    systems).
 135  * Have a document making clear the status of implementation, level of support
 136    available, who the sub-community is and, if applicable, roadmap for inclusion
 137    into the core tier.
 138  * Be restricted to a specific directory or have a consistent pattern (ex.
 139    unique file suffix), making it easy to remove when necessary.
 140
 141 Inclusion Policy
 142 ================
 143
 144 To add a new peripheral component, send an RFC to the appropriate dev list
 145 proposing its addition and explaining how it will meet the support requirements
 146 listed above. Different types of components could require different levels of
 147 detail. when in doubt, ask the community what's the best approach.
 148
 149 Inclusion must reach consensus in the RFC by the community and the approval of
 150 the corresponding review (by multiple members of the community) is the official
 151 note of acceptance.
 152
 153 After merge, there often is a period of transition, where teething issues on
 154 existing buildbots are discovered and fixed. If those cannot be fixed straight
 155 away, the sub-community is responsible for tracking and reverting all the
 156 pertinent patches and retrying the inclusion review.
 157
 158 Once the component is stable in tree, it must follow this policy and the
 159 deprecation rules below apply.
 160
 161 Due to the uncertain nature of inclusion, it's advisable that new components
 162 are not added too close to a release branch. The time will depend on the size
 163 and complexity of the component, so adding release and testing managers on the
 164 RFC and review is strongly advisable.
 165
 166 Deprecation Policy
 167 ==================
 168
 169 The LLVM code base has a number of files that aren't being actively maintained.
 170 But not all of those files are obstructing the development of the project and
 171 so it remains in the repository with the assumption that it could still be
 172 useful for downstream users.
 173
 174 For code to remain in the repository, its presence must not impose an undue
 175 burden on maintaining other components (core or peripheral).
 176
 177 Warnings
 178 --------
 179
 180 There are multiple types of issues that might trigger a request for deprecation,
 181 including (but not limited to):
 182
 183  * Changes in a component consistently break other areas of the project.
 184  * Components go broken for long periods of time (weeks or more).
 185  * Clearly superior alternatives are in use and maintenance is painful.
 186  * Builds and tests are harder / take longer, increasing the cost of
 187    maintenance, overtaking the perceived benefits.
 188
 189 If the maintenance cost is higher than it is acceptable by the majority of
 190 developers, it means that either the sub-community is too small (and the extra
 191 cost should be paid locally), or not active enough (and the problems won't be
 192 fixed any time soon). In either case, removal of such problematic component is
 193 justified.
 194
 195 Steps for removal
 196 -----------------
 197
 198 However clear the needs for removal are, we should take an incremental approach
 199 to deprecating code, especially when there's still a sub-community that cares
 200 about it. In that sense, code will never be removed outright without a series
 201 of steps are taken.
 202
 203 A minimum set of steps should be:
 204  #. A proposal for removal / deactivation should be made to the Discourse forums
 205     (under the appropriate category), with a clear
 206     statement of the maintenance costs imposed and the alternatives, if
 207     applicable.
 208  #. There must be enough consensus on the list that removal is warranted, and no
 209     pending proposals to fix the situation from a sub-community.
 210  #. An announcement for removal must be made on the same lists, with ample time
 211     for downstream users to take action on their local infrastructure. The time
 212     will depend on what is being removed.
 213
 214     #. If a script or documents are to be removed, they can always be pulled
 215        from previous revision, and can be removed within days.
 216     #. if a whole target is removed, we need to first announce publicly, and
 217        potentially mark as deprecated in one release, only to remove on the
 218        next release.
 219     #. Everything else will fall in between those two extremes.
 220  #. The removal is made by either the proposer or the sub-community that used to
 221     maintain it, with replacements and arrangements made atomically on the same
 222     commit.
 223
 224 If a proposal for removal is delayed by the promise a sub-community will take
 225 care of the code affected, the sub-community will have a time to fix all the
 226 issues (depending on each case, as above), and if those are not fixed in time, a
 227 subsequent request for removal should be made and the community may elect to
 228 eject the component without further attempts to fix.
 229
 230 Reinstatement
 231 -------------
 232
 233 If a component is removed from LLVM, it may, at a later date, request inclusion
 234 of a modified version, with evidence that all of the issues were fixed and that
 235 there is a clear sub-community that will maintain it.
 236
 237 By consequence, the pressure on such sub-community will be higher to keep
 238 overall maintenance costs to a minimum and will need to show steps to mitigate
 239 all of the issues that were listed as reasons for its original removal.
 240
 241 Failing on those again, will lead to become a candidate for removal yet again.
 242