docs: add an amber article

This gives a brief introduction to the Amber branch, and where to
find documentation for it.

Reviewed-by: Adam Jackson <ajax@redhat.com>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/18648>

docs/amber.rst

@@ -0,0 +1,46 @@
+Amber Branch
+============
+
+After Mesa 21.3, all non-Gallium DRI drivers were removed from the Mesa
+source-tree. These drivers are still being maintained to some degree,
+but only on the 21.3.x branch, and only for critical fixes.
+
+These drivers include:
+
+-  radeon
+-  r200
+-  i915
+-  i965
+-  nouveau (the DRI driver for NV04-NV20)
+
+At the same time, the OpenSWR Gallium driver was removed from the Mesa
+source-tree, because it was already practically speaking unmaintained and
+the actively maintained LLVMpipe offers much of the same functionality.
+
+Users with Intel GPUs that were using i965 should migrate to either Iris
+or Crocus, depending on their GPU. These drivers generally speaking both
+perform better and have more features than i965 had, and due to sharing
+more code with the rest of the Mesa infrastructure, gets more bugfixes
+and features.
+
+Similarly, users of i915 should migrate to i915g (the Gallium driver for
+the same hardware), as it's still being maintained.
+
+Users who depend on the removed drivers will have to use them built from
+the Amber branch in order to get updates.
+
+Building
+--------
+
+The Amber branch has some extra logic to be able to coexist with recent
+Mesa releases without them stepping on each others toes. In order to
+enable that logic, you need to pass the ``-Damber=true`` flag to Meson.
+
+Documentation
+-------------
+
+On `docs.mesa3d.org <https://docs.mesa3d.org/>`, we currently only
+publish the documentation from our main branch. But you can view the
+documentation for the Amber branch `here
+<https://gitlab.freedesktop.org/mesa/mesa/-/tree/21.3/docs>`_.
+

docs/index.rst

@@ -37,6 +37,7 @@ Linux, FreeBSD, and other operating systems.
    self
    history
    developers
+   amber
    systems
    license
    faq