[gentoo-commits] proj/pms:eapi-5 commit in: /

["Ulrich Mueller" <ulm@gentoo.org>]

commit:     4db51f1d9e77927973c6d23e6fcff62a514c29c9
Author:     Andreas K. Huettel <dilfridge <AT> gentoo <DOT> org>
AuthorDate: Sat Jul 21 21:18:51 2012 +0000
Commit:     Ulrich Mueller <ulm <AT> gentoo <DOT> org>
CommitDate: Sun Aug 12 12:15:55 2012 +0000
URL:        http://git.overlays.gentoo.org/gitweb/?p=proj/pms.git;a=commit;h=4db51f1d

Define stability levels.

---
 ebuild-vars.tex |   27 +++++++++++++++++++++++----
 names.tex       |    8 +-------
 2 files changed, 24 insertions(+), 11 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}
 

diff --git a/names.tex b/names.tex
index fd9731c..decc8f4 100644
--- a/names.tex
+++ b/names.tex
@@ -40,13 +40,7 @@ hyphen. In addition, every repository name must also be a valid package name.
 \label{sec:keyword-names}
 A keyword name may contain any of the characters [\t{A-Za-z0-9\_-}]. It must not begin with a
 hyphen. In contexts where it makes sense to do so, a keyword name may be prefixed by
-a tilde or a hyphen. In \t{KEYWORDS}, \t{-*} is also acceptable as a keyword, to indicate that
-a package will only work on listed targets.
-
-A tilde prefixed keyword is, by convention, used to indicate a less stable package. It is generally
-assumed that any user accepting keyword \t{\textasciitilde{}foo} will also accept \t{foo}.
-
-The exact meaning of any keywords value is beyond the scope of this specification.
+a tilde or a hyphen. In \t{KEYWORDS}, \t{-*} is also acceptable as a keyword.
 
 \subsection{EAPI Names}
 \label{sec:eapi-names}