[docs] Adding target status definition

[rengolin]

Summary

This section of the developer's policy describes the requirements for the targets to become (and remain) as experimental or official back-ends.

I'm avoiding spam, please copy everyone that you feel should see this.

[rengolin]

PS: "6 months" is an arbitrary time. I'm not hung up on that, but I think we should have "some" time frame...

[dschuff]

docs/DeveloperPolicy.rst

581

Maybe add "VM or other software implementation" to the list of possible ways a target can exist? "emulator" doesn't quite cover WebAssembly or BPF, for example.

[chandlerc]

Thanks for writing this up Renato.

I followed up on the original thread as I think some of this is actually setting the bar too high. Want to finish the discussion there first? Or get the non-controversial parts of this in place while that goes on? I have no strong opinions about the most efficacious way to proceed.

[lattner]

I think it absolutely makes sense to encode the policy for this into the developer policy document, but think we should converge on the mailing list before discussing specific wording for it.

[rengolin]

In D22753#495405, @lattner wrote:

I think it absolutely makes sense to encode the policy for this into the developer policy document, but think we should converge on the mailing list before discussing specific wording for it.

Works for me.

[rengolin]

FYI: http://lists.llvm.org/pipermail/llvm-dev/2016-July/102912.html

docs/DeveloperPolicy.rst

   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<LangRef>`)
+  **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<copyright-license-patents>`.
+
+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<CodingStandards>`.
+* 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