From afe50c11965ecc1e0500935a5e3fc737c9875c21 Mon Sep 17 00:00:00 2001
From: Alberto Donizetti <alb.donizetti@gmail.com>
Date: Sat, 19 Oct 2019 12:31:59 +0200
Subject: [PATCH] doc: update ports list description to reflect current status

This change updates the GOARCH/GOOS discussion at the top of the
"Installing Go from source" document to better reflect the current
status. In particular:

- The GOARCH list now focuses on simply listing the supported
architectures, with no notes about their supposed "maturity", since
the same GOARCH can be mature on a GOOS and not so mature on another.

- Outdated notes about some archs being new and "not well-exercised"
have been removed in favour of a following list of which ports are
first class.

- The list of supported OS has been updated (added: AIX, Illumos),
and sorted in alphabetical order.

- A note about the runtime support being the same for all ARCHS,
"including garbage collection and efficient array slicing and" etc etc
has been removed, since it doesn't seem particularly relevant in a
"install from source" instruction page, and it's likely a leftover
from the time this doc page was the landing place for new people and
it felt the need to "sell" Go.

Updates #27689
Fixes #35009

Change-Id: Ic4eca91dca3135adc7bed4fe00b4f157768f0e81
Reviewed-on: https://go-review.googlesource.com/c/go/+/202197
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
---
 doc/install-source.html | 68 ++++++++++++++++-------------------------
 1 file changed, 26 insertions(+), 42 deletions(-)

diff --git a/doc/install-source.html b/doc/install-source.html
index 12b10d5621..918f1a99ae 100644
--- a/doc/install-source.html
+++ b/doc/install-source.html
@@ -33,80 +33,64 @@ compiler using the GCC back end, see
 </p>
 
 <p>
-The Go compilers support nine instruction sets.
-There are important differences in the quality of the compilers for the different
-architectures.
-</p>
+The Go compilers support twelve instruction sets:
 
 <dl>
 <dt>
-	<code>amd64</code> (also known as <code>x86-64</code>)
-</dt>
-<dd>
-	A mature implementation.
-</dd>
-<dt>
-	<code>386</code> (<code>x86</code> or <code>x86-32</code>)
-</dt>
-<dd>
-	Comparable to the <code>amd64</code> port.
-</dd>
-<dt>
-	<code>arm</code> (<code>ARM</code>)
+  <code>amd64</code>, <code>386</code>
 </dt>
 <dd>
-	Supports Linux, FreeBSD, NetBSD, OpenBSD and Darwin binaries. Less widely used than the other ports.
+  The <code>x86</code> instruction set, 64- and 32-bit.
 </dd>
 <dt>
-	<code>arm64</code> (<code>AArch64</code>)
+  <code>arm64</code>, <code>arm</code>
 </dt>
 <dd>
-	Supports Linux and Darwin binaries. New in 1.5 and not as well exercised as other ports.
+  The <code>ARM</code> instruction set, 64-bit (<code>AArch64</code>) and 32-bit.
 </dd>
 <dt>
-	<code>ppc64, ppc64le</code> (64-bit PowerPC big- and little-endian)
+  <code>ppc64</code>, <code>ppc64le</code>
 </dt>
 <dd>
-	Supports Linux binaries. New in 1.5 and not as well exercised as other ports.
+  The 64-bit PowerPC instruction set, big- and little-endian.
 </dd>
 <dt>
-	<code>mips, mipsle</code> (32-bit MIPS big- and little-endian)
+  <code>s390x</code>
 </dt>
 <dd>
-	Supports Linux binaries. New in 1.8 and not as well exercised as other ports.
+  The IBM z/Architecture.
 </dd>
 <dt>
-	<code>mips64, mips64le</code> (64-bit MIPS big- and little-endian)
+  <code>mips64</code>, <code>mips64le</code>, <code>mips</code>,  <code>mipsle</code>
 </dt>
 <dd>
-	Supports Linux binaries. New in 1.6 and not as well exercised as other ports.
+  The <code>MIPS</code> instruction set, big- and little-endian, 64- and 32-bit.
 </dd>
 <dt>
-	<code>s390x</code> (IBM System z)
+  <code>wasm</code>
 </dt>
 <dd>
-	Supports Linux binaries. New in 1.7 and not as well exercised as other ports.
-</dd>
-<dt>
-	<code>wasm</code> (WebAssembly)
-</dt>
-<dd>
-	Targets the WebAssembly platform. New in 1.11 and not as well exercised as other ports.
+  <a href="https://webassembly.org">WebAssembly</a>.
 </dd>
 </dl>
+</p>
 
 <p>
-Except for things like low-level operating system interface code, the run-time
-support is the same in all ports and includes a mark-and-sweep garbage
-collector, efficient array and string slicing, and support for efficient
-goroutines, such as stacks that grow and shrink on demand.
+The compilers can target the AIX, Android, DragonFly BSD, FreeBSD,
+Illumos, Linux, macOS/iOS (Darwin), NetBSD, OpenBSD, Plan 9, Solaris,
+and Windows operating systems (although not all operating systems
+support all architectures).
 </p>
 
 <p>
-The compilers can target the DragonFly BSD, FreeBSD, Linux, NetBSD, OpenBSD,
-macOS (Darwin), Plan 9, Solaris and Windows operating systems.
-The full set of supported combinations is listed in the discussion of
-<a href="#environment">environment variables</a> below.
+A list of ports which are considered "first class" is available at the
+<a href="/wiki/PortingPolicy#first-class-ports">first class ports</a>
+wiki page.
+</p>
+
+<p>
+The full set of supported combinations is listed in the
+discussion of <a href="#environment">environment variables</a> below.
 </p>
 
 <p>
-- 
2.51.0