Define stability levels.

1 files changed, 23 insertions, 4 deletions

diff --git a/ebuild-vars.tex b/ebuild-vars.tex
index 7eaabc5..01d2393 100644
--- a/ebuild-vars.tex
+++ b/ebuild-vars.tex
@@ -47,10 +47,8 @@ Ebuilds may define any of the following variables:
     (see section~\ref{sec:licenses-dir}). See section~\ref{sec:dependencies} for full syntax.
     \label{ebuild-var-LICENSE}
 \item[KEYWORDS] A whitespace separated list of keywords for the ebuild. Each token must be a valid
-    keyword name, as per section~\ref{sec:keyword-names}. May include \t{-*}, which indicates that
-    the package will only work on explicitly listed archs. May include \t{-arch}, which indicates
-    that the package will not work on the specified arch. May be empty, which indicates uncertain
-    functionality on any architecture.
+    keyword name, as per section~\ref{sec:keyword-names}. See section~\ref{sec:keywords} for full
+    syntax.
 \item[IUSE] The \t{USE} flags used by the ebuild. Any eclass that works with \t{USE} flags must
     also set \t{IUSE}, listing only the variables used by that eclass. The package manager is
     responsible for merging these values. See section~\ref{sec:use-iuse-handling} for discussion on
@@ -143,6 +141,27 @@ EAPI, the package manager must make sure that the \t{EAPI} value obtained by sou
 with bash is identical to the EAPI obtained by parsing. The ebuild must be treated as invalid if
 these values are different.
 
+\subsection{Keywords}
+\label{sec:keywords}
+
+Keywords are used to indicate levels of stability of a package on a respective architecture
+\t{arch}. The following conventions are used:
+\begin{itemize}
+\item \t{arch}: Both the package version and the ebuild are widely tested, known to work and not
+    have any serious issues on the indicated platform. This is referred to as a \i{stable keyword}.
+\item \t{\textasciitilde arch}: The package version and the ebuild are believed to work and do
+    not have any known serious bugs, but more testing is required before the package version is
+    considered suitable for obtaining a stable keyword. This is referred to as an \i{unstable
+    keyword} or a \i{testing keyword}.
+\item No keyword: It is not known whether the package will work, or insufficient testing has
+    occurred.
+\item \t{-arch}: The package version will not work on the architecture.
+\end{itemize}
+The \t{-*} keyword is used to indicate package versions which are not worth trying to test on
+unlisted architectures.
+
+An empty \t{KEYWORDS} variable indicates uncertain functionality on any architecture.
+
 \subsection{\t{RDEPEND} value}
 \label{sec:rdepend-depend}