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>