[gentoo-pms] [PATCH 1/2] Appendix: Split off retroactive changes from historical curiosities.

[gentoo-pms] [PATCH 1/2] Appendix: Split off retroactive changes from historical curiosities.

[Ulrich Müller]

[-- Attachment #1: Type: text/plain, Size: 2790 bytes --]

---
 appendices.tex | 25 ++++++++++++++-----------
 1 file changed, 14 insertions(+), 11 deletions(-)

diff --git a/appendices.tex b/appendices.tex
index 8c97734..dd40041 100644
--- a/appendices.tex
+++ b/appendices.tex
@@ -26,12 +26,13 @@ been abused in the past.
 
 \chapter{Historical Curiosities}
 
-The items described in this chapter are included for information only. Unless otherwise noted,
-they were deprecated or abandoned long before \t{EAPI} was introduced. Ebuilds must not use these
-features, and package managers should not be changed to support them.
+\section{Long-obsolete Features}
 
-\section{If-else USE Blocks}
+The items described in this section are included for information only. Unless otherwise noted, they
+were deprecated or abandoned long before EAPI was introduced. Ebuilds must not use these features,
+and package managers should not be changed to support them.
 
+\subsection{If-else USE blocks}
 Historically, Portage supported if-else use conditionals, as shown by
 listing~\ref{lst:if-else-use-listing}. The block before the colon would be taken if the condition
 was met, and the block after the colon would be taken if the condition was not met.
@@ -49,27 +50,29 @@ DEPEND="
 \end{verbatim}
 \end{listing}
 
-\section{cvs Versions}
-
+\subsection{CVS versions}
 Portage has very crude support for CVS packages. The package \t{foo} could contain a file named
 \t{foo-cvs.1.2.3.ebuild}. This version would order \e{higher} than any non-CVS version (including
 \t{foo-2.ebuild}). This feature has not seen real world use and breaks versioned dependencies, so
 it must not be used.
 
-\section{use.defaults}
-
+\subsection{use.defaults}
 The \t{use.defaults} file in the profile directory was used to implement `autouse'---switching USE
 flags on or off depending upon which packages are installed. It was deprecated long ago and finally
 removed in 2009.
 
-\section{Old-style Virtuals}
+\section{Retroactive Changes}
+
+In some exceptional cases, changes to the specification have been approved by the Gentoo Council
+without introducing a new EAPI. This section lists such retroactive changes.
 
+\subsection{Old-style virtuals}
 Historically, virtuals were special packages rather than regular ebuilds. An ebuild could specify in
 the \t{PROVIDE} metadata that it supplied certain virtuals, and the package manager had to bear this
 in mind when handling dependencies.
 
-Old-style virtuals were supported by EAPIs \t{0}, \t{1}, \t{2}, \t{3} and \t{4}, and were phased out
-via GLEP 37~\cite{Glep37}.
+Old-style virtuals were supported by EAPIs \t{0}, \t{1}, \t{2}, \t{3} and \t{4}. They were phased
+out via GLEP 37~\cite{Glep37} and finally removed in 2011.
 
 % vim: set filetype=tex fileencoding=utf8 et tw=100 spell spelllang=en :
 
-- 
2.14.2

[-- Attachment #2: Type: application/pgp-signature, Size: 490 bytes --]

[gentoo-pms] [PATCH 2/2] Appendix: Add a list of notable retroactive changes.

[Ulrich Müller]

[-- Attachment #1: Type: text/plain, Size: 4585 bytes --]

This should contain all retroactive changes that were approved by the
council (and after EAPIs 0, 1 and 2 were finalised).
---
 appendices.tex  | 30 ++++++++++++++++++++++++++++++
 ebuild-vars.tex |  1 +
 names.tex       |  1 +
 pms.bib         |  8 ++++++++
 4 files changed, 40 insertions(+)

diff --git a/appendices.tex b/appendices.tex
index dd40041..7227fc8 100644
--- a/appendices.tex
+++ b/appendices.tex
@@ -66,6 +66,10 @@ removed in 2009.
 In some exceptional cases, changes to the specification have been approved by the Gentoo Council
 without introducing a new EAPI. This section lists such retroactive changes.
 
+\subsection{Bash version}
+EAPIs \t{0}, \t{1} and \t{2} originally specified GNU Bash version 3.0. This was retroactively
+updated to version 3.2 (see table~\ref{tab:bash-version}) in November 2009.
+
 \subsection{Old-style virtuals}
 Historically, virtuals were special packages rather than regular ebuilds. An ebuild could specify in
 the \t{PROVIDE} metadata that it supplied certain virtuals, and the package manager had to bear this
@@ -74,6 +78,32 @@ in mind when handling dependencies.
 Old-style virtuals were supported by EAPIs \t{0}, \t{1}, \t{2}, \t{3} and \t{4}. They were phased
 out via GLEP 37~\cite{Glep37} and finally removed in 2011.
 
+\subsection{EAPI parsing}
+The method to specify the EAPI of an ebuild used to be a shell variable assignment, and the
+package manager had to source the ebuild in order to determine the EAPI. Therefore any ebuild using
+a future EAPI would still have to be sourceable by old package managers, which imposed restrictions
+e.\,g.\ on updating the Bash version or on possible changes of global scope functions. Several
+approaches to overcome this limitation were discussed, notably GLEP 55~\cite{Glep55}, which was
+rejected though.
+
+The current syntax of the \t{EAPI} assignment statement (see section~\ref{sec:eapi}), allowing
+the package manager to obtain the EAPI from the ebuild by a regular expression match and without
+sourcing it, was introduced in May 2012.
+
+\subsection{Package names}
+Previously, package names were only required not to end in a hyphen followed by one or more digits.
+In October 2012 this was tightened to the specification in section~\ref{sec:package-names}, namely
+that they must not end in a hyphen followed by anything resembling a package version.
+
+\subsection{Asterisk in dependency specification}
+In the \t{=} dependency operator specified in section~\ref{sec:dep-operator}, an asterisk used to
+induce string prefix comparison instead of the normal version comparison logic. That could lead to
+surprising results, e.\,g.\ \t{=dev-lang/perl-5.2*} matching \t{dev-lang/perl-5.22.0}. Moreover,
+implementation in package managers deviated from what was specified.
+
+String prefix matching was effective in EAPIs \t{0}, \t{1}, \t{2}, \t{3}, \t{4} and \t{5}. It was
+retroactively dropped in favour of the current behaviour in October 2015.
+
 % vim: set filetype=tex fileencoding=utf8 et tw=100 spell spelllang=en :
 
 %%% Local Variables:
diff --git a/ebuild-vars.tex b/ebuild-vars.tex
index b910f25..8c05ce9 100644
--- a/ebuild-vars.tex
+++ b/ebuild-vars.tex
@@ -115,6 +115,7 @@ Ebuilds may define any of the following variables:
 \end{centertable}
 
 \subsection{EAPI}
+\label{sec:eapi}
 
 An empty or unset \t{EAPI} value is equivalent to \t{0}. Ebuilds must not assume that they will get
 a particular one of these two values if they are expecting one of these two values.
diff --git a/names.tex b/names.tex
index 6767c55..af6a50a 100644
--- a/names.tex
+++ b/names.tex
@@ -13,6 +13,7 @@ a hyphen, a dot or a plus sign.
 names will contain a hyphen.
 
 \subsection{Package names}
+\label{sec:package-names}
 A package name may contain any of the characters [\t{A-Za-z0-9+_-}]. It must not begin with a
 hyphen or a plus sign, and must not end in a hyphen followed by anything matching the version
 syntax described in section~\ref{sec:version-spec}.
diff --git a/pms.bib b/pms.bib
index 2221f75..914c41f 100644
--- a/pms.bib
+++ b/pms.bib
@@ -14,6 +14,14 @@
     howpublished = "\url{https://wiki.gentoo.org/wiki/GLEP:44}"
 }
 
+@misc{Glep55,
+    author = {Piotr Jaroszyński},
+    title = {{GLEP} 55: Use {EAPI}-suffixed ebuilds},
+    year = 2007,
+    month = Dec,
+    howpublished = "\url{https://wiki.gentoo.org/wiki/GLEP:55}"
+}
+
 @misc{Glep68,
     author = {Michał Górny},
     title = {{GLEP} 68: Package and category metadata},
-- 
2.14.2

[-- Attachment #2: Type: application/pgp-signature, Size: 490 bytes --]

[gentoo-pms] [PATCH 0/2] Document notable retroactive changes

[Ulrich Müller]

[-- Attachment #1: Type: text/plain, Size: 803 bytes --]

In the past we had several retroactive changes to the specification.
This series of two patches tries to document them. Sometimes the line
between a true change and a clarification is not clear cut. Therefore
I have included only such retroactive changes that went through
council approval. I have also omitted any changes that were done
before the first council-approved version (which included EAPIs 0, 1
and 2).

Ulrich Müller (2):
  Appendix: Split off retroactive changes from historical curiosities.
  Appendix: Add a list of notable retroactive changes.

 appendices.tex  | 55 ++++++++++++++++++++++++++++++++++++++++++++-----------
 ebuild-vars.tex |  1 +
 names.tex       |  1 +
 pms.bib         |  8 ++++++++
 4 files changed, 54 insertions(+), 11 deletions(-)

-- 
2.14.2

[-- Attachment #2: Type: application/pgp-signature, Size: 490 bytes --]

[gentoo-pms] Re: [PATCH 0/2] Document notable retroactive changes

[Ulrich Mueller]

[-- Attachment #1: Type: text/plain, Size: 456 bytes --]

> In the past we had several retroactive changes to the specification.
> This series of two patches tries to document them. Sometimes the
> line between a true change and a clarification is not clear cut.
> Therefore I have included only such retroactive changes that went
> through council approval. I have also omitted any changes that were
> done before the first council-approved version (which included EAPIs
> 0, 1 and 2).

Pushed to master.

Ulrich

[-- Attachment #2: Type: application/pgp-signature, Size: 490 bytes --]