Rewrite the platform Tier definitions.

Rewrite the prose description of Tiers to be structured as bullet
lists of guarantees to users from the Project, guarantees to
developers from the Project, and obligations on developers.

This includes definitions of userland and kernel ABIs as well as
documenting our current practice of ABI stability.

The committments for ports are still vague and will require further
refinement.

Move the Tier status of architectures out of the committers guide and
into a table on the platforms page the website listing the Tier for
each architecture across currently supported stable branches as well
as the projected Tiers for the next stable branch (in this case,
13.x).  The table also lists individual TARGET_ARCH values to permit
more granularity in Tier definitions (e.g. hard-float vs soft-float).

Update the Unsupported Platforms table to only list removed
architectures and include the last supported release of these
architectures.  This required adding anchors for relevant releases on
the releases page.

Reviewed by:	bcr
Discussed with:	developers@
Differential Revision:	https://reviews.freebsd.org/D22439

1 files changed, 299 insertions, 137 deletions

diff --git a/en_US.ISO8859-1/articles/committers-guide/article.xml b/en_US.ISO8859-1/articles/committers-guide/article.xml
index 369af10b3c..32c94c627f 100644
--- a/en_US.ISO8859-1/articles/committers-guide/article.xml
+++ b/en_US.ISO8859-1/articles/committers-guide/article.xml
@@ -4002,170 +4002,332 @@ Relnotes:           yes</programlisting>
 	documentation team, security officer, and release engineering
 	teams.  Diversity in hardware support broadens the options for
 	&os; consumers by offering new features and usage
-	opportunities (such as support for 64-bit CPUs, use in
-	embedded environments, etc.), but these benefits must always
+	opportunities, but these benefits must always
 	be carefully considered in terms of the real-world maintenance
 	cost associated with additional platform support.</para>
 
-      <para>The &os; Project differentiates platform targets into
-	four tiers.  Each tier includes a specification of the
-	requirements for an architecture to be in that tier,
-	as well as specifying the obligations of developers with
-	regards to the platform.  In addition, a policy is defined
-	regarding the circumstances required to change the tier
-	of an architecture.</para>
+      <para>The &os; Project differentiates platform targets into four
+        tiers.  Each tier includes a list of guarantees consumers may
+        rely on as well as obligations by the Project and developers
+        to fulfill those guarantees.  These lists define the minimum
+        guarantees for each tier.  The Project and developers may
+        provide additional levels of support beyond the minimum
+        guarantees for a given tier, but such additional support is
+        not guaranteed.  Each platform target is assigned to a
+        specific tier for each stable branch.  As a result, a platform
+        target might be assigned to different tiers on concurrent
+        stable branches.</para>
     </sect2>
 
     <sect2>
-      <title>Tier 1: Fully Supported Architectures</title>
-
-      <para>Tier 1 platforms are fully supported by the security
-	officer, release engineering, and toolchain maintenance staff.
-	New features added to the operating system must be fully
-	functional across all Tier 1 architectures for every release
-	(features which are inherently architecture-specific, such as
-	support for hardware device drivers, may be exempt from this
-	requirement).  In general, all Tier 1 platforms must have
-	build and test automation support either in the FreeBSD.org
-	cluster, or easily available for all developers.  Embedded
-	platforms may substitute an emulator available in the
-	FreeBSD.org cluster for actual hardware.</para>
-
-      <para>Tier 1 architectures are expected to be Production Quality
-	with respects to all aspects of the &os; operating system,
-	including installation and development environments.</para>
-
-      <para>Tier 1 architectures are expected to be completely
-	integrated into the source tree and have all features
-	necessary to produce an entire system relevant for that target
-	architecture.  Tier 1 architectures generally have at least 6
-	active developers.</para>
-
-      <para>Tier 1 architectures are expected to be fully supported by
-	the ports system.  All the ports should build on a Tier 1
-	platform, or have the appropriate filters to prevent the
-	inappropriate ones from building there.  The packaging system
-	must support all Tier 1 architectures.  To ensure an
-	architecture's Tier 1 status, proponents of that architecture
-	must show that all relevant packages can be built on that
-	platform.</para>
-
-      <para>Tier 1 embedded architectures must be able to cross-build
-	packages on at least one other Tier 1 architecture.  The
-	packages must be the most relevant for the platform, but may
-	be a non-empty subset of those that build natively.</para>
-
-      <para>Tier 1 architectures must be fully documented.  All basic
-	operations need to be covered by the handbook or other
-	documents.  All relevant integration documentation must also
-	be integrated into the tree, or readily available.</para>
-
-      <para>Current Tier 1 platforms are &arch.i386; and
-	&arch.amd64;.</para>
+      <title>Platform Targets</title>
+
+      <para>Support for a hardware platform consists of two
+        components: kernel support and userland Application Binary
+        Interfaces (ABIs).  Kernel platform support includes things
+        needed to run a &os; kernel on a hardware platform such as
+        machine-dependent virtual memory management and device
+        drivers.  A userland ABI specifies an interface for user
+        processes to interact with a &os; kernel and base system
+        libraries.  A userland ABI includes system call interfaces,
+        the layout and semantics of public data structures, and the
+        layout and semantics of arguments passed to subroutines.  Some
+        components of an ABI may be defined by specifications such as
+        the layout of C++ exception objects or calling conventions for
+        C functions.</para>
+
+      <para>A &os; kernel also uses an ABI (sometimes referred to as
+        the Kernel Binary Interface (KBI)) which includes the
+        semantics and layouts of public data structures and the layout
+        and semantics of arguments to public functions within the
+        kernel itself.</para>
+
+      <para>A &os; kernel may support multiple userland ABIs.  For
+        example, &os;'s amd64 kernel supports &os; amd64 and i386
+        userland ABIs as well as Linux x86_64 and i386 userland ABIs.
+        A &os; kernel should support a <quote>native</quote> ABI as
+        the default ABI.  The native <quote>ABI</quote> generally
+        shares certain properties with the kernel ABI such as the C
+        calling convention, sizes of basic types, etc.</para>
+
+      <para>Tiers are defined for both kernels and userland ABIs.  In
+        the common case, a platform's kernel and &os; ABIs are
+        assigned to the same tier.</para>
     </sect2>
 
     <sect2>
-      <title>Tier 2: Developmental Architectures</title>
-
-      <para>Tier 2 platforms are not supported by the security officer
-	and release engineering teams.  Platform maintainers are
-	responsible for toolchain support in the tree.  The toolchain
-	maintainers are expected to work with the platform maintainers
-	to refine these changes.  Major new toolchain components are
-	allowed to break support for Tier 2 architectures if the
-	&os;-local changes have not been incorporated upstream.
-	The toolchain maintainers are expected to provide prompt
-	review of any proposed changes and cannot block, through their
-	inaction, changes going into the tree.  New features added to
-	&os; should be feasible to implement on these platforms,
-	but an implementation is not required before the feature may
-	be added to the &os; source tree.  New features that may be
-	difficult to implement on Tier 2 architectures should provide
-	a means of disabling them on those architectures.  The
-	implementation of a Tier 2 architecture may be committed to
-	the main &os; tree as long as it does not interfere with
-	production work on Tier 1 platforms, or substantially with
-	other Tier 2 platforms.  Before a Tier 2 platform can be added
-	to the &os; base source tree, the platform must be able to
-	boot multi-user on actual hardware.  Generally, there must be
-	at least three active developers working on the
-	platform.</para>
-
-      <para>Tier 2 architectures are usually systems targeted at Tier
-	1 support, but that are still under development.
-	Architectures reaching end of life may also be moved from Tier
-	1 status to Tier 2 status as the availability of resources to
-	continue to maintain the system in a Production Quality state
-	diminishes.  Well supported niche architectures may also be
-	Tier 2.</para>
-
-      <para>Tier 2 architectures have basic support for them
-	integrated into the ports infrastructure.  They may have cross
-	compilation support added, at the discretion of portmgr.  Some
-	ports must built natively into packages if the package system
-	supports that architecture.  If not integrated into the base
-	system, some external patches for the architecture for ports
-	must be available.</para>
-
-      <para>Tier 2 architectures can be integrated into the &os;
-	handbook.  The basics for how to get a system running must be
-	documented, although not necessarily for every single board or
-	system a Tier 2 architecture supports.  The supported hardware
-	list must exist and be relatively recent.  It should be
-	integrated into the &os; documentation.</para>
-
-      <para>Current Tier 2 platforms are &arch.arm;, &arch.arm64;,
-	&arch.mips;, &arch.powerpc;, and &arch.sparc64;.</para>
+      <title>Tier 1: Fully-Supported Architectures</title>
+
+      <para>Tier 1 platforms are the most mature &os; platforms.
+        They are supported by the security officer, release
+        engineering, and port management teams.  Tier 1 architectures
+        are expected to be Production Quality with respect to all
+        aspects of the &os; operating system, including installation
+        and development environments.</para>
+
+      <para>The &os; Project provides the following guarantees to
+        consumers of Tier 1 platforms:</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para>Official &os; release images will be provided by the
+	    release engineering team.</para>
+	</listitem>
+	<listitem>
+	  <para>Binary updates and source patches for Security
+	    Advisories and Errata Notices will be provided for
+	    supported releases.</para>
+	</listitem>
+	<listitem>
+	  <para>Source patches for Security Advisories will be
+	    provided for supported branches.</para>
+	</listitem>
+	<listitem>
+	  <para>Binary updates and source patches for cross-platform
+	    Security Advisories will typically be provided at the time
+	    of the announcement.</para>
+	</listitem>
+	<listitem>
+	  <para>Changes to userland ABIs will generally include
+	    compatibility shims to ensure correct operation of
+	    binaries compiled against any stable branch where the
+	    platform is Tier 1.  These shims might not be enabled in
+	    the default install.  If compatibility shims are not
+	    provided for an ABI change, the lack of shims will be
+	    clearly documented in the release notes.</para>
+	</listitem>
+	<listitem>
+	  <para>Changes to certain portions of the kernel ABI will
+	    include compatibility shims to ensure correct operation of
+	    kernel modules compiled against the oldest supported
+	    release on the branch.  Note that not all parts of the
+	    kernel ABI are protected.</para>
+	</listitem>
+	<listitem>
+	  <para>Official binary packages for third party software will
+	    be provided by the ports team.  For embedded
+	    architectures, these packages may be cross-built from a
+	    different architecture.</para>
+	</listitem>
+	<listitem>
+	  <para>Most relevant ports should either build or have the
+	    appropriate filters to prevent inappropriate ones from
+	    building.</para>
+	</listitem>
+	<listitem>
+	  <para>New features which are not inherently
+	    platform-specific will be fully functional on all Tier 1
+	    architectures.</para>
+	</listitem>
+	<listitem>
+	  <para>Features and compatibility shims used by binaries
+	    compiled against older stable branches may be removed in
+	    newer major versions.  Such removals will be clearly
+	    documented in the release notes.</para>
+	</listitem>
+	<listitem>
+	  <para>Tier 1 platforms should be fully documented.  Basic
+	    operations will be documented in the &os; Handbook.</para>
+	</listitem>
+	<listitem>
+	  <para>Tier 1 platforms will be included in the source
+	    tree.</para>
+	</listitem>
+	<listitem>
+	  <para>Tier 1 platforms should be self-hosting either via the
+	    in-tree toolchain or an external toolchain.  If an
+	    external toolchain is required, official binary packages
+	    for an external toolchain will be provided.</para>
+	</listitem>
+      </itemizedlist>
+
+      <para>To maintain maturity of Tier 1 platforms, the &os; Project
+        will maintain the following resources to support
+        development:</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para>Build and test automation support either in the
+	    FreeBSD.org cluster or some other location easily
+	    available for all developers.  Embedded platforms may
+	    substitute an emulator available in the FreeBSD.org
+	    cluster for actual hardware.</para>
+	</listitem>
+	<listitem>
+	  <para>Inclusion in the <userinput>make universe</userinput>
+	    and <userinput>make tinderbox</userinput> targets.</para>
+	</listitem>
+	<listitem>
+	  <para>Dedicated hardware in one of the &os; clusters for
+	    package building (either natively or via
+	    qemu-user).</para>
+	</listitem>
+      </itemizedlist>
+
+      <para>Collectively, developers are required to provide the
+        following to maintain the Tier 1 status of a platform:</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para>Changes to the source tree should not knowingly break
+	    the build of a Tier 1 platform.</para>
+	</listitem>
+	<listitem>
+	  <para>Tier 1 architectures must have a mature, healthy
+	    ecosystem of users and active developers.</para>
+	</listitem>
+	<listitem>
+	  <para>Developers should be able to build packages on
+	    commonly available, non-embedded Tier 1 systems.  This can
+	    mean either native builds if non-embedded systems are
+	    commonly available for the platform in question, or it can
+	    mean cross-builds hosted on some other Tier 1
+	    architecture.</para>
+	</listitem>
+	<listitem>
+	  <para>Changes cannot break the userland ABI.  If an ABI
+	    change is required, ABI compatibility for existing
+	    binaries should be provided via use of symbol versioning
+	    or shared library version bumps.</para>
+	</listitem>
+	<listitem>
+	  <para>Changes merged to stable branches cannot break the
+	    protected portions of the kernel ABI.  If a kernel ABI
+	    change is required, the change should be modified to
+	    preserve functionality of existing kernel modules.</para>
+	</listitem>
+      </itemizedlist>
+    </sect2>
+
+    <sect2>
+      <title>Tier 2: Developmental and Niche Architectures</title>
+
+      <para>Tier 2 platforms are functional, but less mature &os;
+        platforms.  They are not supported by the security officer,
+        release engineering, and port management teams.</para>
+
+      <para>Tier 2 platforms may be Tier 1 platform candidates that
+        are still under active development.  Architectures reaching
+        end of life may also be moved from Tier 1 status to Tier 2
+        status as the availability of resources to continue to
+        maintain the system in a Production Quality state diminishes.
+        Well-supported niche architectures may also be Tier 2.</para>
+
+      <para>The &os; Project provides the following guarantees to
+        consumers of Tier 2 platforms:</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para>The ports infrastructure should include basic support
+	    for Tier 2 architectures sufficient to support building
+	    ports and packages.  This includes support for basic
+	    packages such as ports-mgmt/pkg, but there is no guarantee
+	    that arbitrary ports will be buildable or
+	    functional.</para>
+	</listitem>
+	<listitem>
+	  <para>New features which are not inherently
+	    platform-specific should be feasible on all Tier 2
+	    architectures if not implemented.</para>
+	</listitem>
+	<listitem>
+	  <para>Tier 2 platforms will be included in the source
+	    tree.</para>
+	</listitem>
+	<listitem>
+	  <para>Tier 2 platforms should be self-hosting either via the
+	    in-tree toolchain or an external toolchain.  If an
+	    external toolchain is required, official binary packages
+	    for an external toolchain will be provided.</para>
+	</listitem>
+	<listitem>
+	  <para>Tier 2 platforms should provide functional kernels and
+	    userlands even if an official release distribution is not
+	    provided.</para>
+	</listitem>
+      </itemizedlist>
+
+      <para>To maintain maturity of Tier 2 platforms, the &os; Project
+        will maintain the following resources to support
+        development:</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para>Inclusion in the <userinput>make universe</userinput>
+	    and <userinput>make tinderbox</userinput> targets.</para>
+	</listitem>
+      </itemizedlist>
+
+      <para>Collectively, developers are required to provide the
+        following to maintain the Tier 2 status of a platform:</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para>Changes to the source tree should not knowingly break
+	    the build of a Tier 2 platform.</para>
+	</listitem>
+	<listitem>
+	  <para>Tier 2 architectures must have an active ecosystem of
+	    users and developers.</para>
+	</listitem>
+	<listitem>
+	  <para>While changes are permitted to break the userland ABI,
+	    the ABI should not be broken gratuitously.  Significant
+	    userland ABI changes should be restricted to major
+	    versions.</para>
+	</listitem>
+	<listitem>
+	  <para>New features that are not yet implemented on Tier 2
+	    architectures should provide a means of disabling them on
+	    those architectures.</para>
+	</listitem>
+      </itemizedlist>
     </sect2>
 
     <sect2>
       <title>Tier 3: Experimental Architectures</title>
 
-      <para>Tier 3 platforms are not supported by the security officer
-	and release engineering teams.  At the discretion of the
-	toolchain maintainers, they may be supported in the toolchain.
-	Tier 3 platforms are architectures in the early stages of
-	development, for non-mainstream hardware platforms, or which
-	are considered legacy systems unlikely to see broad future
-	use.  Initial support for Tier 3 platforms is worked on
-	in external SCM repositories.
-	The transition to &os;'s subversion takes place after
-	the platform boots multi-user on hardware; sharing via
-	subversion is needed for wider exposure; and multiple
-	developers are actively working on the platform.
-	Platforms that transition to Tier 3 status may be
-	removed from the tree if they are no longer actively supported
-	by the &os; developer community at the discretion of the
-	release engineer.</para>
-
-      <para>Tier 3 platforms may have ports support, either integrated
-	or external, but do not require it.</para>
-
-      <para>Tier 3 platforms must have the basics documented for how
-	to build a kernel and how to boot it on at least one target
-	hardware or emulation environment.  This documentation need
-	not be integrated into the &os; tree.</para>
-
-      <para>Current Tier 3 platforms are &arch.riscv;.</para>
+      <para>Tier 3 platforms have at least partial &os; support.  They
+        are <emphasis>not</emphasis> supported by the security
+        officer, release engineering, and port management
+        teams.</para>
+
+      <para>Tier 3 platforms are architectures in the early stages of
+        development, for non-mainstream hardware platforms, or which
+        are considered legacy systems unlikely to see broad future
+        use.  Initial support for Tier 3 platforms may exist in a
+        separate repository rather than the main source
+        repository.</para>
+
+      <para>The &os; Project provides no guarantees to consumers of
+        Tier 3 platforms and is not committed to maintaining resources
+        to support development.  Tier 3 platforms may not always be
+        buildable, nor are any kernel or userland ABIs considered
+        stable.</para>
     </sect2>
 
     <sect2>
       <title>Tier 4: Unsupported Architectures</title>
 
-      <para>Tier 4 systems are not supported in any form by the
+      <para>Tier 4 platforms are not supported in any form by the
 	project.</para>
 
-      <para>All systems not otherwise classified into a support tier
-	are Tier 4 systems.</para>
+      <para>All systems not otherwise classified are Tier 4 systems.
+        When a platform transitions to Tier 4, all support for the
+        platform is removed from the source and ports trees.  Note
+        that ports support should remain as long as the platform is
+        supported in a branch supported by ports.</para>
     </sect2>
 
     <sect2>
       <title>Policy on Changing the Tier of an Architecture</title>
 
       <para>Systems may only be moved from one tier to another by
-	approval of the &os; Core Team, which shall make that
-	decision in collaboration with the Security Officer, Release
-	Engineering, and toolchain maintenance teams.</para>
+        approval of the &os; Core Team, which shall make that decision
+        in collaboration with the Security Officer, Release
+        Engineering, and ports management teams.  For a platform to be
+        promoted to a higher tier, any missing support guarantees must
+        be satisfied before the promotion is completed.</para>
     </sect2>
   </sect1>