[PATCH] D23162: [docs] Adding target status definition to dev policy

[andreybokhanko via llvm-commits]

Looks good for me now (I don't even have any nitpicks... amazing! :-)) -- thank you, Renato!

Yours,
Andrey

> 5 авг. 2016 г., в 18:40, Renato Golin <renato.golin at linaro.org> написал(а):
> 
> rengolin removed rL LLVM as the repository for this revision.
> rengolin updated this revision to Diff 66963.
> rengolin added a comment.
> 
> 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 :)
> 
> 
> https://reviews.llvm.org/D23162
> 
> Files:
>  docs/DeveloperPolicy.rst
> 
> Index: docs/DeveloperPolicy.rst
> ===================================================================
> --- docs/DeveloperPolicy.rst
> +++ docs/DeveloperPolicy.rst
> @@ -553,6 +553,82 @@
>   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
> 
> 
> <D23162.66963.patch>