Index: docs/DeveloperPolicy.rst =================================================================== --- docs/DeveloperPolicy.rst +++ docs/DeveloperPolicy.rst @@ -553,6 +553,66 @@ release notes so that it's clear to external users who do not follow the project how the C API is changing and evolving. +New Targets +----------- + +LLVM is very receptive to new targets, even experimental ones, but a number of +problems can appear when adding new large portions of code, and back-ends are +normally added in bulk. Revisions of large pieces of code is hard, especially +when the reviewers don't know the full implications of the new back-end with +details (which is usually the case), makes for a very error prone process. + +For these reasons, new targets are *always* added as **experimental** until +they can be proven stable, and then moved to non-experimental. The difference +between both classes is that experimental targets are not built by default +(need to be added to -DLLVM_TARGETS_TO_BUILD at CMake time). + +There's also the issue of keeping the targets downstream instead of submitting +upstream. Secrecy is a reason for companies to keeping them downstream, but +openness and quality concerns are reasons for the *community* to prefer it +remains downstream, too. + +So, the basic rules for a back-end to be upstreamed in **experimental** mode are: + +* There must be an active community behind the target. This community will be + the maintainers of the target by providing buildbots, fixing bugs, answering + the LLVM community's questions and making sure the new target doesn't break + any of the other targets, or generic code. +* The target must exist in some form (hardware, emulators) and be easily + accessible by the community. Either open source, free, cheap or remote access + provided by the target maintainers. +* There must be some documents describing the target: ISA, ABI, etc. Code review + will be based on those documents, and their accuracy will dictate the quality + of support by the rest of the community. +* The code must be free of contentious issues, for example, large changes in how + the IR behaves or should be formed by the front-ends, unless agreed by the + majority of the community via refactoring of the (:doc:`IR standard`) + **before** the merge of the new target changes, following the IR backwards + compatibility described in this document. +* The code has a compatible license, patent and copyright statements, or can be + converted by the LLVM's :ref:`own model`. + +In addition, the rules for a back-end to be marked as **official** are: + +* The target must have been in the tree for at least 6 months, with active + contributions including: adding more tests conforming to the documents, fixing + bugs reported by unrelated/generic changes, providing support to other members + of the community. +* The target's code must have been adapted to this developers policy as well as + the :doc:`coding standards`. +* The test coverage is broad and well written (small tests, documented). Where + applicable, both the ``check-all`` and ``test-suite`` must pass in at least + one configuration (publicly demonstrated, ex. via buildbots). + +After targets are made official, they'll need to be maintained with the same +level of quality as *all* those requirements above. Degradation in support, +documentation or test coverage will make the target as nuisance to other targets +and be considered a candidate for deprecation and ultimately removed. + +In essences, these rules are necessary for targets to retain their statuses, but +they're also markers to define bit-rot, and will be used to clean up the tree +from unmaintained targets. + .. _copyright-license-patents: Copyright, License, and Patents