1============================= 2LLVM Community Support Policy 3============================= 4 5As a compilation infrastructure, LLVM has multiple types of users, both 6downstream and upstream, of many combinations of its projects, tools and 7libraries. 8 9There 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 11associated tools (debugger, linker, object file manipulation, etc). These 12components are present in the public release on our supported architectures 13and operating systems and the whole community must maintain and care about. 14 15There are, however, other components within the main repository that either 16cater to a specific sub-community of LLVM (upstream or downstream) or 17help parts of the community to integrate LLVM into their own development tools 18or external projects. Those parts of the main repository don't always have 19rigorous testing like the core parts, nor are they validated and shipped with 20our public upstream releases. 21 22Even not being a core part of the project, we have enough sub-communities 23needing those changes with enough overlap that having them in the main 24repository is beneficial to minimise the repetition of those changes in all 25the external repositories that need them. 26 27But the maintenance costs of such diverse ecosystem is non trivial, so we divide 28the level of support in two tiers: core and peripheral, with two 29different levels of impact and responsibilities. Those tiers refer only to the 30main repository (``llvm-project``) and not the other repositories in our git 31project, unless explicitly stated. 32 33Regardless of the tier, all code must follow the existing policies on quality, 34reviews, style, etc. 35 36Core Tier 37========= 38 39The core tier encompasses all of the code in the main repository that is 40in production, is actively tested and released in a regular schedule, including 41core LLVM APIs and infrastructure, front/middle/back-ends, run-time libraries, 42tools, etc. 43 44It is the responsibility of **every** LLVM developer to care for the core tier 45regardless of where their work is applied to. 46 47What is covered 48--------------- 49 50The 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 59Requirements 60------------ 61 62Code 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 70Peripheral Tier 71=============== 72 73The peripheral tier encompass the parts of LLVM that cater to a specific 74sub-community and which don't usually affect the core components directly. 75 76This includes experimental back-ends, disabled-by-default options and 77alternative paths (work-in-progress replacements) in the same repository, as 78well as separate efforts to integrate LLVM development with local practices. 79 80It is the responsibility of each sub-community to care about their own parts 81and the intersection of that with the core tier and other peripheral parts. 82 83There 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 93What is covered 94--------------- 95 96The 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 103Requirements 104------------ 105 106Code 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 112Code 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 127Code 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 141Inclusion Policy 142================ 143 144To add a new peripheral component, send an RFC to the appropriate dev list 145proposing its addition and explaining how it will meet the support requirements 146listed above. Different types of components could require different levels of 147detail. when in doubt, ask the community what's the best approach. 148 149Inclusion must reach consensus in the RFC by the community and the approval of 150the corresponding review (by multiple members of the community) is the official 151note of acceptance. 152 153After merge, there often is a period of transition, where teething issues on 154existing buildbots are discovered and fixed. If those cannot be fixed straight 155away, the sub-community is responsible for tracking and reverting all the 156pertinent patches and retrying the inclusion review. 157 158Once the component is stable in tree, it must follow this policy and the 159deprecation rules below apply. 160 161Due to the uncertain nature of inclusion, it's advisable that new components 162are not added too close to a release branch. The time will depend on the size 163and complexity of the component, so adding release and testing managers on the 164RFC and review is strongly advisable. 165 166Deprecation Policy 167================== 168 169The LLVM code base has a number of files that aren't being actively maintained. 170But not all of those files are obstructing the development of the project and 171so it remains in the repository with the assumption that it could still be 172useful for downstream users. 173 174For code to remain in the repository, its presence must not impose an undue 175burden on maintaining other components (core or peripheral). 176 177Warnings 178-------- 179 180There are multiple types of issues that might trigger a request for deprecation, 181including (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 189If the maintenance cost is higher than it is acceptable by the majority of 190developers, it means that either the sub-community is too small (and the extra 191cost should be paid locally), or not active enough (and the problems won't be 192fixed any time soon). In either case, removal of such problematic component is 193justified. 194 195Steps for removal 196----------------- 197 198However clear the needs for removal are, we should take an incremental approach 199to deprecating code, especially when there's still a sub-community that cares 200about it. In that sense, code will never be removed outright without a series 201of steps are taken. 202 203A minimum set of steps should be: 204 #. A proposal for removal / deactivation should be made to the developers' 205 mailing lists (``llvm-dev``, ``cfe-dev``, ``lldb-dev``, etc), 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 224If a proposal for removal is delayed by the promise a sub-community will take 225care of the code affected, the sub-community will have a time to fix all the 226issues (depending on each case, as above), and if those are not fixed in time, a 227subsequent request for removal should be made and the community may elect to 228eject the component without further attempts to fix. 229 230Reinstatement 231------------- 232 233If a component is removed from LLVM, it may, at a later date, request inclusion 234of a modified version, with evidence that all of the issues were fixed and that 235there is a clear sub-community that will maintain it. 236 237By consequence, the pressure on such sub-community will be higher to keep 238overall maintenance costs to a minimum and will need to show steps to mitigate 239all of the issues that were listed as reasons for its original removal. 240 241Failing on those again, will lead to become a candidate for removal yet again. 242 243