eipp: let apt make a plan, not make stuff plane

Julian noticed on IRC that I fall victim to a lovely false friend by
calling referring to a 'planer' all the time even through these are
machines to e.g. remove splinters from woodwork ("make stuff plane").
The term I meant is written in german in this way (= with a single n)
but in english there are two, aka: 'planner'.

As that is unreleased code switching all instances without any
transitional provisions. Also the reason why its skipped in changelog.

Thanks: Julian Andres Klode
Gbp-Dch: Ignore

1 files changed, 0 insertions, 298 deletions

diff --git a/doc/external-installation-planer-protocol.txt b/doc/external-installation-planer-protocol.txt
deleted file mode 100644
index 916982ca1..000000000
--- a/doc/external-installation-planer-protocol.txt
+++ /dev/null
@@ -1,298 +0,0 @@
-# APT External Installation Planer Protocol (EIPP) - version 0.1
-
-This document describes the communication protocol between APT and
-external installation planer. The protocol is called APT EIPP, for "APT
-External Installation Planer Protocol".
-
-
-## Terminology
-
-In the following we use the term **architecture qualified package name**
-(or *arch-qualified package names* for short) to refer to package
-identifiers of the form "package:arch" where "package" is a package name
-and "arch" a dpkg architecture.
-
-
-## Components
-
-- **APT**: we know this one.
-- APT is equipped with its own **internal planer** for the order of
-  package installation (and removal) which is identified by the string
-  `internal`.
-- **External planer**: an *external* software component able to plan an
-  installation on behalf of APT.
-
-At each interaction with APT, a single planer is in use.  When there is
-a total of 2 or more planers, internals or externals, the user can
-choose which one to use.
-
-Each planer is identified by an unique string, the **planer name**.
-Planer names must be formed using only alphanumeric ASCII characters,
-dashes, and underscores; planer names must start with a lowercase ASCII
-letter.  The special name `internal` denotes APT's internal planer, is
-reserved, and cannot be used by external planers.
-
-
-## Installation
-
-Each external planer is installed as a file under Dir::Bin::Planers (see
-below), which defaults to `/usr/lib/apt/planers`. We will assume in the
-remainder of this section that such a default value is in effect.
-
-The naming scheme is `/usr/lib/apt/planers/NAME`, where `NAME` is the
-name of the external planer.
-
-Each file under `/usr/lib/apt/planers` corresponding to an external
-planer must be executable.
-
-No non-planer files must be installed under `/usr/lib/apt/planers`, so
-that an index of available external planers can be obtained by listing
-the content of that directory.
-
-
-## Configuration
-
-Several APT options can be used to affect installation planing in APT.
-An overview of them is given below. Please refer to proper APT
-configuration documentation for more, and more up to date, information.
-
-- **APT::Planer**: the name of the planer to be used for dependency
-  solving. Defaults to `internal`
-
-- **Dir::Bin::Planers**: absolute path of the directory where to look
-  for external solvers. Defaults to `/usr/lib/apt/planers`.
-
-
-## Protocol
-
-When configured to use an external planer, APT will resort to it to
-decide in which order packages should be installed, configured and
-removed.
-
-The interaction happens **in batch**: APT will invoke the external
-planer passing the current status of (half-)installed packages and of
-packages which should be installed, as well as a request denoting the
-packages to install, reinstall, remove and purge.  The external planer
-will compute a valid plan of when and how to call the low-level package
-manager (like dpkg) with each package to satisfy the request.
-
-External planers are invoked by executing them. Communications happens
-via the file descriptors: **stdin** (standard input) and **stdout**
-(standard output). stderr is not used by the EIPP protocol. Planers can
-therefore use stderr to dump debugging information that could be
-inspected separately.
-
-After invocation, the protocol passes through a sequence of phases:
-
-1. APT invokes the external planer
-2. APT send to the planer an installation planer **scenario**
-3. The planer calculates the order. During this phase the planer may
-   send, repeatedly, **progress** information to APT.
-4. The planer sends back to APT an **answer**, i.e. either a *solution*
-   or an *error* report.
-5. The external planer exits
-
-
-### Scenario
-
-A scenario is a text file encoded in a format very similar to the "Deb
-822" format (AKA "the format used by Debian `Packages` files"). A
-scenario consists of two distinct parts: a **request** and a **package
-universe**, occurring in that order. The request consists of a single
-Deb 822 stanza, while the package universe consists of several such
-stanzas. All stanzas occurring in a scenario are separated by an empty
-line.
-
-
-#### Request
-
-Within an installation planer scenario, a request represents the action
-on packages requested by the user explicitly as well as potentially
-additions calculated by a dependency resolver which the user has
-accepted.
-
-An installation planer is not allowed to suggest the modification of
-package states (e.g. removing additional packages) even if it can't
-calculate a solution otherwise – the planer must error out in such
-a case. An exception is made for scenarios which contain packages which
-aren't completely installed (like half-installed or trigger-awaiting):
-Solvers are free to move these packages to a fully installed state (but
-are still forbidden to remove them).
-
-A request is a single Deb 822 stanza opened by a mandatory Request field
-and followed by a mixture of action, preference, and global
-configuration fields.
-
-The value of the **Request:** field is a string describing the EIPP
-protocol which will be used to communicate and especially which answers
-APT will understand. At present, the string must be `EIPP 0.1`. Request
-fields are mainly used to identify the beginning of a request stanza;
-their actual values are otherwise not used by the EIPP protocol.
-
-The following **configuration fields** are supported in request stanzas:
-
-- **Architecture:** (mandatory) The name of the *native* architecture on
-  the user machine (see also: `dpkg --print-architecture`)
-
-- **Architectures:** (optional, defaults to the native architecture) A
-  space separated list of *all* architectures known to APT (this is
-  roughly equivalent to the union of `dpkg --print-architecture` and
-  `dpkg --print-foreign-architectures`)
-
-The following **action fields** are supported in request stanzas:
-
-- **Install:** (optional, defaults to the empty string) A space
-  separated list of arch-qualified package names, with *no version
-  attached*, to install. This field denotes a list of packages that the
-  user wants to install, usually via an APT `install` request.
-
-- **Remove:** (optional, defaults to the empty string) Same syntax of
-  Install. This field denotes a list of packages that the user wants to
-  remove, usually via APT `remove` or `purge` requests.
-
-- **ReInstall:** (optional, defaults to the empty string) Same syntax of
-  Install. This field denotes a list of packages which are installed,
-  but should be reinstalled again e.g. because files shipped by that
-  package were removed or corrupted accidentally, usually requested via
-  an APT `install` request with the `--reinstall` flag.
-
-The following **preference fields** are supported in request stanzas:
-
-- **Planer:** (optional, defaults to the empty string) a purely
-  informational string specifying to which planer this request was send
-  initially.
-
-- **Immediate-Configuration:** (option, unset by default) A boolean
-  value defining if the planer should try to configure all packages as
-  quickly as possible (true) or shouldn't perform any kind of immediate
-  configuration at all (false). If not explicitly set with this field
-  the planer is free to pick either mode or implementing e.g. a mode
-  which configures only packages immediately if they are flagged as
-  `Essential` (or are dependencies of packages marked as `Essential`).
-
-- **Allow-Temporary-Remove-of-Essentials** (optional, defaults to `no`).
-  A boolean value allowing the planer (if set to yes) to temporarily
-  remove an essential package. Associated with the APT::Force-LoopBreak
-  configuration option its main use is highlighting that planers who do
-  temporary removes must take special care in terms of essentials. Legit
-  uses of this option by users is very uncommon, traditionally
-  a situation in which it is needed indicates a packaging error.
-
-
-#### Package universe
-
-A package universe is a list of Deb 822 stanzas, one per package, called
-**package stanzas**. Each package stanzas starts with a Package
-field. The following fields are supported in package stanzas:
-
-- The fields Package, Version, Architecture (all mandatory) and
-  Multi-Arch, Pre-Depends, Depends, Conflicts, Breaks, Essential
-  (optional) as they are contained in the dpkg database (see the manpage
-  `dpkg-query (1)`).
-
-- **Status:** (optional, defaults to `uninstalled`). Allowed values are
-  the "package status" names as listed in `dpkg-query (1)` and visible
-  e.g. in the dpkg database as the second value in the space separated
-  list of values in the Status field there. In other words: Neither
-  desired action nor error flags are present in this field in EIPP!
-
-- **APT-ID:** (mandatory). Unique package identifier, according to APT.
-
-
-### Answer
-
-An answer from the external planer to APT is either a *solution* or an
-*error*.
-
-The following invariant on **exit codes** must hold true. When the
-external planer is *able to find a solution*, it will write the solution
-to standard output and then exit with an exit code of 0. When the
-external planer is *unable to find a solution* (and is aware of that),
-it will write an error to standard output and then exit with an exit
-code of 0.  An exit code other than 0 will be interpreted as a planer
-crash with no meaningful error about dependency resolution to convey to
-the user.
-
-
-#### Solution
-
-A solution is a list of Deb 822 stanzas. Each of them could be an:
-
-- unpack stanza to cause the extraction of a package to the disk
-
-- configure stanza to cause an unpacked package to be configured and
-  therefore the installation to be completed
-
-- remove stanza to cause the removal of a package from the system
-
-An **unpack stanza** starts with an Unpack field and supports the
-following fields:
-
-- **Unpack:** (mandatory). The value is a package identifier,
-  referencing one of the package stanzas of the package universe via its
-  APT-ID field.
-
-- All fields supported by package stanzas.
-
-**Configure** and **Remove stanzas** require and support the same
-fields with the exception of the Unpack field which is replaced in
-these instances with the Configure or Remove field respectively.
-
-The order of the stanzas is significant (unlike in the EDSP protocol),
-with the first stanza being the first performed action. If multiple
-stanzas of the same type appear in direct succession the order in such
-a set isn't significant through.
-
-The solution needs to be valid (it is not allowed to configure a package
-before it was unpacked, dependency relations must be satisfied, …), but
-they don't need to be complete: A planer can and should expect that any
-package which wasn't explicitly configured will be configured at the end
-automatically. That also means through that a planer is not allowed to
-produce a solution in which a package remains unconfigured.
-
-In terms of expressivity, all stanzas can carry one single field each, as
-APT-IDs are enough to pinpoint packages to be installed/removed. Nonetheless,
-for protocol readability, it is recommended that planers either add
-unconditionally the fields Package, Version, and Architecture to all
-install/remove stanzas or, alternatively, that they support a `--verbose`
-command line flag that explicitly enables the output of those fields in
-solutions.
-
-#### Error
-
-An error is a single Deb 822 stanza, starting the field Error. The
-following fields are supported in error stanzas:
-
-- **Error:** (mandatory). The value of this field is ignored, although
-  it should be a unique error identifier, such as a UUID.
-
-- **Message:** (mandatory). The value of this field is a text string,
-  meant to be read by humans, that explains the cause of the planer
-  error.  Message fields might be multi-line, like the Description field
-  in the dpkg database. The first line conveys a short message, which
-  can be explained in more details using subsequent lines.
-
-
-### Progress
-
-During dependency solving, an external planer may send progress
-information to APT using **progress stanzas**. A progress stanza starts
-with the Progress field and might contain the following fields:
-
-- **Progress:** (mandatory). The value of this field is a date and time
-  timestamp, in RFC 2822 format. The timestamp provides a time
-  annotation for the progress report.
-
-- **Percentage:** (optional). An integer from 0 to 100, representing the
-  completion of the installation planning process, as declared by the
-  planer.
-
-- **Message:** (optional). A textual message, meant to be read by the
-  APT user, telling what is going on within the installation planer
-  (e.g. the current phase of planning, as declared by the planer).
-
-
-# Future extensions
-
-Potential future extensions to this protocol are to be discussed on
-deity@lists.debian.org.