From 65168d983419365ee0a71b8da2a089e657ae0f8d Mon Sep 17 00:00:00 2001 From: Julian Andres Klode Date: Mon, 10 Feb 2025 15:14:02 +0100 Subject: Add doc/design/install.md: Installation design This documents the user interface for apt install, currently only the solution screen as implemented in the 3.0 output format. --- doc/design/install.md | 199 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 199 insertions(+) create mode 100644 doc/design/install.md diff --git a/doc/design/install.md b/doc/design/install.md new file mode 100644 index 000000000..e54cf6835 --- /dev/null +++ b/doc/design/install.md @@ -0,0 +1,199 @@ +# Installation design + +## Solution screen + +After calculating the changes to be performed, APT needs to present the solution to the +user. + +### General layout + +The screen is organized as a series of blocks, followed by warnings and notices +and finally a prompt. + + BLOCK + + BLOCK + + W: A warning + Continue? [Y/n] + +Each block is separated by an empty line, and follows one of two schemes: + +1. Title, Details, optional notes + + This block should have a short title describing what is being shown such as + "Installing" or "Summary", and one or more line of details, indented by two + spaces. An optional final line may contain an additional note: + + Title: + Detail + Detail + Notes + + The notes element should be used sparingly, for example, in the autoremove note: + + No longer needed: + package1 package3 + package2 package4 + Use 'apt autoremove' to remove no longer needed packages. + + The note should be a single sentence, with complete punctuation. + + +2. Text blobs are short paragraphs that consist only of informational text. + They may appear before or after the changes lists. + An example would be the "news" inserted by the Ubuntu Pro hooks. + Text blobs should be two-three lines long, and have block style formatting, + with a line length of no more than 79 characters, for example: + + This is an informational blob with no information that appears before + the list of changes. It contains a lot of text saying stuff. + + Installing: + package + + Installing dependencies: + dependency + + This is an important blob with important information that appears + after the list of changes. It contains a lot of text saying stuff. + + Summary: + Upgrading: 0, Installing: 23, Removing: 0, Not Upgrading: 1 + Download size: 6,947 kB + Space needed: 44.7 MB / 16.8 GB available + + Continue? [Y/n] + + They should usually not use any formatting inside the text. + +### Order of blocks; standard set of blocks + +Generally speaking blocks, should be ordered by increasing importance, and +context relevance. For example, while Suggested packages are less important +then the packages being installed, they are Suggested *by* the packages being +installed, so printing them first is awkward. + +The standard blocks and their order are: + +1. 'No longer needed' - list of packages that can be autoremoved, and a note how to do so +1. 'Upgrading' - list of packages being upgraded +1. 'Installing' - a list of packages being installed manually +1. 'Installing dependencies' - a list of packages being installed automatically +1. 'Recommended packages' - a list of Recommends that did not get installed +1. 'Suggested packages' - a list of Suggests that did not get installed (Suggests are not installed by default) +1. 'Not upgrading yet' - a list of packages not yet upgraded due to phasing +1. 'Not upgrading' - a list of packages not being upgraded due to dependency issues +1. 'DOWNGRADING' - a list of packages being downgraded, with emphasis as it is unsupported. +1. 'REMOVING' - a list of packages being removed, with emphasis as removals are dangerous +1. 'REMOVING Essential packages:' - a list of Essential packages being removed and a note that it is dangerous. +1. 'Summary' - contains a summary of the changes to be performed + +Note that blocks that describe an action are given as a progressive verb, whereas non-action +blocks have a non-verb title. + +### Package list layouts + +Package lists can be rendered in one of three formats: + +1. The standard format is a columnar view following ls(1), top to bottom, left to right, + showing only the package names. + If the packages fit in a single line, they are rendered as such. + + Example of multiple lines: + + package1 shortname3 otherpackage5 + longpackagename2 short4 yetanotherpackage6 + + Example for a single line + + package1 longpackagename2 shortname3 + +2. The `-V` format presents one package per line with additional version information, + in one of the following forms: + + name (version) + name (old version => new version) + +3. The classic layout ("wall of text") is a left to right, top to bottom list that + wraps around, with package names separated by spaces: + + package1 longpackagename2 shortname3 + short4 otherpackage5 yetanotherpackage6 + + This is available in the `--no-list-columns` option. + +### Colors and Highlighting of package lists +A solution is essentially a diff to be applied to your system, so we highlight packages +being added as green, and packages being removed as red. +There are a couple more cases of changes calculated, though: + +Packages that are being suggested: They are not installed by default, but you can install +them to enhance the functionality of the packages being installed. +We do not want to specifically highlight those, as it's informational only. +What may be interesting is visually distinguishing Suggests that are not even available +in your configured sources, as that is allowed (e.g. main packages Suggest multiverse, +but multiverse is disabled). + +Recommends that could not be installed: They are similar to Suggests, but normally +installed by default, so seeing this section is a bit unexpected. We do not believe +they warrant further highlighting, as the section appearing is more than enough. + +Upgrades do not change the set of packages installed, but merely their versions, so from +the "present the solution as a diff" approach, it is awkward to present them as green. However, +green is also associated with "good" and upgrades are a normal thing for packages to do, +so highlighting them green is not entirely wrong. + +Not highlighting upgrades would make them look similar to non-change lists, like Suggests +and Recommends that failed to install, which would be confusing to the user because it is +making *some* change. + +Downgrades are the opposite of upgrades, but importantly they are *unsupported*, we do +not ever test them. It makes sense to highlight their unsupportedness, hence we mark +them yellow. + +#### Emphasis in the absence of colors and styles +The headings for removals and downgrades are in upper case to emphasise their +danger. + +### The solution summary + +The summary contains a line with package change counts per category, followed +by the download size, following by any space changes. + + + Summary: + Upgrading: 0, Installing: 23, Removing: 0, Not Upgrading: 1 + Download size: 6,947 kB + Space needed: 44.7 MB / 16.8 GB available + +**Space changes** are listed as one of the following: + +1. The space needed is known, but we can't figure out available space: + + Space needed: 44.7 MB + +2. Space needed and available space in the /usr partition + + Space needed: 44.7 MB / 16.8 GB available + +3. Space needed and available space, with kernels being installed and a separate /boot: + + Space needed: 44.7 MB / 16.8 GB available + └─ in /boot: 110 MB / 533 MB available + +4. Freed space inverts the order of words vs "Space needed" to make the difference more striking: + + Freed space: 44.7 MB + +### Prompting + +The final prompt asks the user if they want to continue by prompting either + + Continue? [Y/n] + +with the default being 'yes' (as indicated by the upper case character), or + + Continue anyway? [y/N] + +with a default of 'no', for example, in the case warnings were shown. -- cgit v1.2.3-70-g09d2