Index: llvm/docs/GettingInvolved.rst =================================================================== --- llvm/docs/GettingInvolved.rst +++ llvm/docs/GettingInvolved.rst @@ -12,6 +12,7 @@ Contributing DeveloperPolicy CodeReview + SupportPolicy SphinxQuickstartTemplate Phabricator HowToSubmitABug @@ -28,6 +29,9 @@ :doc:`CodeReview` The LLVM project's code-review process. +:doc:`SupportPolicy` + The LLVM support policy for core and non-core components. + :doc:`SphinxQuickstartTemplate` A template + tutorial for writing new Sphinx documentation. It is meant to be read in source form. Index: llvm/docs/SupportPolicy.rst =================================================================== --- /dev/null +++ llvm/docs/SupportPolicy.rst @@ -0,0 +1,222 @@ +============================= +LLVM Community Support Policy +============================= + +As a compilation infrastructure, LLVM has multiple types of users, both +downstream and upstream, of many combinations of its projects, tools and +libraries. + +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. + +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. + +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. + +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 (``llvm-project``) and not the other repositories in our git +project, unless explicitly stated. + +Regardless of the tier, all code must follow the existing policies on quality, +reviews, style, etc. + +Core Tier +========= + +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. + +It is the responsibility of **every** LLVM developer to care for the core tier +regardless of where their work is applied to. + +What is covered +--------------- + +The core tier is composed of: + * Core code (``llvm-project``) present in official releases and buildbots: + compiler, debugger, linker, libraries, etc, including infrastructure code + (table-gen, lit, file-check, unit-tests, etc). + * Build infrastructure that creates releases and buildbots (CMake, scripts). + * `Phabricator `_ and + `buildbot `_ infrastructure. + * The `test-suite `_. + +Requirements +------------ + +Code in this tier must: + * 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. + * 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. + +Peripheral Tier +=============== + +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. + +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. + +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. + +There are three main groups of code that fit in this category: + * Code that is making its way into LLVM, via the `experimental `_ + roadmap or similar efforts. + * 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. + * 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. + +What is covered +--------------- + +The peripheral tier is composed of: + * Experimental targets and options that haven't been enable by default yet. + * Main repository projects that don't get released or regularly tested. + * Legacy tools and scripts that aren't used in upstream validation. + * Alternative build systems (ex. GN, Bazel) and related infrastructure. + * Tools support (ex. gdb scripts, editor configuration, helper scripts). + +Requirements +------------ + +Code in this tier must: + * Have a clear benefit for remaining in the main repository, catering to at + least one active sub-community (upstream or downstream). + * Be actively maintained by such sub-community and have its problems addressed + in a timely manner, even if concerns come from outside of the sub-community. + +Code in this tier must **not**: + * 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. + * Negatively affect development of core tier code, with the sub-community + involved responsible for making changes to address specific concerns. + * 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. + * Impose sub-optimal implementation strategies on core tier components as a + result of idiosyncrasies in the peripheral component. + * Have build infrastructure that spams all developers about their breakages. + * Fall into disrepair. This is a reflection of lack of an active sub-community + and will result in removal. + +Code in this tier should: + * Have infrastructure to test, whenever meaningful, with either no warnings or + notification contained within the sub-community. + * 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). + * 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. + * Be restricted to a specific directory or have a consistent pattern (ex. + unique file suffix), making it easy to remove when necessary. + +Deprecation Policy +================== + +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. + +There usually isn't a drive to actively clean up legacy code unless there's an +issue. As stated in the developer's policy on `adding new targets `_, +"degradation in support" makes code "a candidate for deprecation" and eventual +removal. + +But for code to remain in the tiers above, they must not impose degradation in +their own support but also in other parts of the code. + +Warnings +-------- + +There are multiple types of issues that might trigger a request for deprecation, +including (but not limited to): + + * Changes in a component consistently break other areas of the project. + * Components go broken for long periods of time (weeks or more). + * Clearly superior alternatives are in use and maintenance is painful. + * Builds and tests are harder / take longer, increasing the cost of + maintenance, overtaking the perceived benefits. + +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. + +Steps for removal +----------------- + +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. + +A minimum set of steps should be: + #. A proposal for removal / deactivation should be made to the developers' + mailing lists (``llvm-dev``, ``cfe-dev``, ``lldb-dev``, etc), with a clear + statement of the maintenance costs imposed and the alternatives, if + applicable. + #. There must be enough consensus on the list that removal is warranted, and no + pending proposals to fix the situation from a sub-community. + #. 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. + + #. If a script or documents are to be removed, they can always be pulled + from previous revision, and can be removed within days. + #. 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. + #. Everything else will fall in between those two extremes. + #. 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. + +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. + +Reinstatement +------------- + +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. + +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. + +Failing on those again, will lead to become a candidate for removal yet again. +