[docs] Adding target status definition to dev policy

[rengolin]

Summary

Making explicit our current policy to accept new targets as experimental, official and maintained.

[mehdi_amini]

Fine with me.

[mehdi_amini]

(And thanks Renato for taking the time to lead and write this)

[andreybokhanko]

Hi Renato,

Thank you for working on this!

My comments (purely subjective ones, really, not hard objections at all) are below.

Yours,
Andrey

docs/DeveloperPolicy.rst

565

Should we stress *always*? In the discussion you present an example of a target (BPF) that was added as an official right away (http://lists.llvm.org/pipermail/llvm-dev/2016-July/102505.html). Maybe it's better to say *practically always* or something like this?

572–573

I don't understand this (most likely my bad) -- how keeping a target downstream helps with openness and quality concerns?

625–628

I'm not entirely happy with the wording, which makes target maintenance look like a daily walk through a minefield, with each single mistake evaluated and penalties taken. I guess your idea is that adhering to the rules and policies shouldn't be forgotten once a target becomes experimental / official. IMHO, just saying that "continuous violations of aforementioned rules and policies could lead to complete removal of the target from the code base" would be sufficient.

[rengolin]

docs/DeveloperPolicy.rst

565

The BPF back-end started experimental, then moved to non-experimental.

http://lists.llvm.org/pipermail/llvm-dev/2015-June/086492.html

So, I think making it a requirement is a strong suggestion that we don't want to fast-track targets, since they won't have proven that they can "cope with upstream development pace for the required time".

572–573

No, that's a horrible paragraph, but I didn't know how to say it better. :)

My point here is that, in the same way the target's community (a company, maybe) may want to keep the targets downstream (secrecy, product roadmap, etc), the LLVM community may also refuse to accept a target upstream just because the company wants to. Ie. this is a two-way street.

For example, when the Lanai back-end was proposed, there were concerns that the lack of documents, emulators and targets available would make it unusable for everyone *but* the Lanai community, so a cost to everyone else for the sake of saving time to the Lanai community.

But later they have shown interest in publishing ISA docs and will make an emulator open source, so that has shown interest, usefulness and also reduces the tension in the LLVM community.

I'd love if someone could convey that idea into a concise and meaningful paragraph. :)

625–628

I agree, it is a bit harsh. Wasn't meant to be. :)

I'll re-word.

[rengolin]

Changes:

• Removed weird paragraph. The intention was good, but the wording was horrible. We can add it later, since the policy itself already covers most of what I wanted to say anyway.
• Re-worded the continuation clause to make it sound less harsh. We're really lenient to bit-rotting targets... (see CppBackend :)

[rengolin]

Ping. @lattner?

[lattner]

Overall, looks great. I added some specific detailed comments above. Once you addressed those, I think this is good to merge, thank you for driving this forward Renato!

docs/DeveloperPolicy.rst

572

I think that the very first bullet point is that the target must have a code owner. The active community is the second bullet. This allows you to divide the responsibilities a bit: the code owner makes sure that changes to the target get reviewed and steers the overall effort, but the community ensures that bots and other larger issues are handled.

576

Nit-pick: Please use American spelling: "behavior".

584

Link to the IR compatibility section of the policy?

586

License compatibility is not enough, it must be the same license. Please say something like:

"The code conforms to all of the policies laid out in this developer policy document, including license, patent, and coding standards."

598

If we're going to pick an arbitrary timeframe, it might as well be specific. Just say "3 months" instead of "2-3 months".

611

please expand "ex." to "for example". This is more comprehensible to non-english-as-first-language readers.

[rengolin]

Thanks Chris!

Addressed your concerns and committed on r278971.

[lattner]

Thanks Renato!

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).
+
+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. This
+  behaviour is expected to continue throughout the lifetime of the
+  target's code.
+
+* 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 the developer's policy
+  document.
+
+* The code has a compatible license, patent and copyright statements,
+  or can be converted to LLVM's :ref:`own model<copyright-license-patents>`.
+
+* The target should have either reasonable documentation on how it
+  works (ISA, ABI, etc.) or a publicly available simulator/hardware
+  (either free or cheap enough), so that developers can validate
+  assumptions, understand constraints and review code that can affect
+  the target. Preferably both.
+
+In addition, the rules for a back-end to be marked as **official** are:
+
+* The target must have addressed every other minimum requirement and
+  have been stable in tree for at least 2-3 months. This cool down
+  period is to make sure that the back-end and the target community can
+  endure continuous upstream development for the foreseeable future.
+
+* The target's code must have been completely adapted to this policy
+  as well as the :doc:`coding standards<CodingStandards>`. Any exceptions that
+  were made to move into experimental mode must have been fixed **before**
+  becoming official.
+
+* The test coverage needs to be broad and well written (small tests,
+  well documented). The build target ``check-all`` must pass with the
+  new target built, and where applicable, the ``test-suite`` must also
+  pass without errors, in at least one configuration (publicly
+  demonstrated, ex.  via buildbots).
+
+* Public buildbots need to be created and actively maintained, unless
+  the target requires no additional buildbots (ex. ``check-all`` covers
+  all tests). The more relevant and public the new target's CI infrastructure
+  is, the more the LLVM community will embrace it.
+
+To **continue** as a supported and official target:
+
+* The maintainer(s) must continue following these rules throughout the lifetime
+  of the target. Continuous violations of aforementioned rules and policies
+  could lead to complete removal of the target from the code base.
+
+* 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 gain and retain their
+status, but 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