Skip to content
This repository was archived by the owner on Mar 28, 2020. It is now read-only.

Commit 302f15f

Browse files
committed
[docs] Adding "new target" rules to dev policy
Making explicit our current policy to accept new targets as experimental and later official. Every new target should follow these rules to be added, and kept relevant in the upstream tree. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@278971 91177308-0d34-0410-b5e6-96231b3b80d8
1 parent 7d7a23e commit 302f15f

File tree

1 file changed

+83
-0
lines changed

1 file changed

+83
-0
lines changed

docs/DeveloperPolicy.rst

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -169,6 +169,8 @@ on a patch, but only people with Subversion write access can approve it.
169169
There is a web based code review tool that can optionally be used
170170
for code reviews. See :doc:`Phabricator`.
171171

172+
.. _code owners:
173+
172174
Code Owners
173175
-----------
174176

@@ -497,6 +499,8 @@ list, development list, or LLVM bug tracker component. If someone sends you
497499
a patch privately, encourage them to submit it to the appropriate list first.
498500

499501

502+
.. _IR backwards compatibility:
503+
500504
IR Backwards Compatibility
501505
--------------------------
502506

@@ -553,6 +557,85 @@ C API Changes
553557
release notes so that it's clear to external users who do not follow the
554558
project how the C API is changing and evolving.
555559

560+
New Targets
561+
-----------
562+
563+
LLVM is very receptive to new targets, even experimental ones, but a number of
564+
problems can appear when adding new large portions of code, and back-ends are
565+
normally added in bulk. Revisions of large pieces of code is hard, especially
566+
when the reviewers don't know the full implications of the new back-end with
567+
details (which is usually the case), makes for a very error prone process.
568+
569+
For these reasons, new targets are *always* added as *experimental* until
570+
they can be proven stable, and then moved to non-experimental. The difference
571+
between both classes is that experimental targets are not built by default
572+
(need to be added to -DLLVM_TARGETS_TO_BUILD at CMake time).
573+
574+
So, the basic rules for a back-end to be upstreamed in **experimental** mode are:
575+
576+
* Every target must have a :ref:`code owner<code owners>`. The `CODE_OWNERS.TXT`
577+
file has to be updated as part of the first merge. The code owner makes sure
578+
that changes to the target get reviewed and steers the overall effort.
579+
580+
* There must be an active community behind the target. This community
581+
will be the maintainers of the target by providing buildbots, fixing
582+
bugs, answering the LLVM community's questions and making sure the new
583+
target doesn't break any of the other targets, or generic code. This
584+
behavior is expected to continue throughout the lifetime of the
585+
target's code.
586+
587+
* The code must be free of contentious issues, for example, large
588+
changes in how the IR behaves or should be formed by the front-ends,
589+
unless agreed by the majority of the community via refactoring of the
590+
(:doc:`IR standard<LangRef>`) **before** the merge of the new target changes,
591+
following the :ref:`IR backwards compatibility`.
592+
593+
* The code conforms to all of the policies laid out in this developer policy
594+
document, including license, patent, and coding standards.
595+
596+
* The target should have either reasonable documentation on how it
597+
works (ISA, ABI, etc.) or a publicly available simulator/hardware
598+
(either free or cheap enough), so that developers can validate
599+
assumptions, understand constraints and review code that can affect
600+
the target. Preferably both.
601+
602+
In addition, the rules for a back-end to be marked as **official** are:
603+
604+
* The target must have addressed every other minimum requirement and
605+
have been stable in tree for at least 3 months. This cool down
606+
period is to make sure that the back-end and the target community can
607+
endure continuous upstream development for the foreseeable future.
608+
609+
* The target's code must have been completely adapted to this policy
610+
as well as the :doc:`coding standards<CodingStandards>`. Any exceptions that
611+
were made to move into experimental mode must have been fixed **before**
612+
becoming official.
613+
614+
* The test coverage needs to be broad and well written (small tests,
615+
well documented). The build target ``check-all`` must pass with the
616+
new target built, and where applicable, the ``test-suite`` must also
617+
pass without errors, in at least one configuration (publicly
618+
demonstrated, for example, via buildbots).
619+
620+
* Public buildbots need to be created and actively maintained, unless
621+
the target requires no additional buildbots (ex. ``check-all`` covers
622+
all tests). The more relevant and public the new target's CI infrastructure
623+
is, the more the LLVM community will embrace it.
624+
625+
To **continue** as a supported and official target:
626+
627+
* The maintainer(s) must continue following these rules throughout the lifetime
628+
of the target. Continuous violations of aforementioned rules and policies
629+
could lead to complete removal of the target from the code base.
630+
631+
* Degradation in support, documentation or test coverage will make the target as
632+
nuisance to other targets and be considered a candidate for deprecation and
633+
ultimately removed.
634+
635+
In essences, these rules are necessary for targets to gain and retain their
636+
status, but also markers to define bit-rot, and will be used to clean up the
637+
tree from unmaintained targets.
638+
556639
.. _copyright-license-patents:
557640

558641
Copyright, License, and Patents

0 commit comments

Comments
 (0)