@@ -169,6 +169,8 @@ on a patch, but only people with Subversion write access can approve it.
169
169
There is a web based code review tool that can optionally be used
170
170
for code reviews. See :doc: `Phabricator `.
171
171
172
+ .. _code owners :
173
+
172
174
Code Owners
173
175
-----------
174
176
@@ -497,6 +499,8 @@ list, development list, or LLVM bug tracker component. If someone sends you
497
499
a patch privately, encourage them to submit it to the appropriate list first.
498
500
499
501
502
+ .. _IR backwards compatibility :
503
+
500
504
IR Backwards Compatibility
501
505
--------------------------
502
506
@@ -553,6 +557,85 @@ C API Changes
553
557
release notes so that it's clear to external users who do not follow the
554
558
project how the C API is changing and evolving.
555
559
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
+
556
639
.. _copyright-license-patents :
557
640
558
641
Copyright, License, and Patents
0 commit comments