This is a partial specification for the graphical interface of [[https://launchpad.net/sessioninstaller|SessionInstaller]] and [[https://launchpad.net/aptdaemon|Aptdaemon]]. For the most part, Aptdaemon should have no UI of its own, with progress displayed in a separate program such as Ubuntu Software Center or Update Manager. But when there are errors, or when a non-specialist application (such as a media player) asks for installation of a particular package, Aptdaemon should present its own UI to maximize consistency and thoroughness. ''See also'' [[http://pad.ubuntu.com/N7uJiU5h6j|aptdaemon error messages]]. <> <> == Data for packages == A package is presented to humans using information derived from the `app-install-data` package, the archive index, and the package’s Debian control file. Ubuntu Software Center, Update Manager, file managers (“Open With…”), and Aptdaemon should share the code they use to calculate this information. <> [[#icon|#]] The '''icon''' should be the icon supplied for the application by your current theme, if there is one; otherwise the icon provided by `app-install-data`, if there is one; otherwise the generic package icon. ''This may be enhanced later for more specialized generic icons.'' <> [[#title|#]] The '''title''' should be the application Name, if there is one; otherwise the package synopsis (the first line of [[http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Description|the Description field]]) with its first word capitalized. If this leaves multiple packages with the same title, the package name should be appended in brackets to the title of each of them: “{Previous Title} ({package name})”. (This is the same approach used for [[SessionMenu#account-switching|disambiguating account names in Ubuntu’s session menu]].) '''Test case:''' In Ubuntu Software Center, search for the “backintime-gnome” package. The item should have the title “Back In Time (backintime-gnome)”. <> [[#short-name|#]] The '''short name''' should be the application Name, if there is one; otherwise the package name. (This is for use in more technical contexts than the Title; for example, in [[SoftwareCenter#history|Ubuntu Software Center’s “History” section]].) <> [[#summary|#]] The '''summary''' should be the application Comment, if there is one; otherwise the package synopsis (with at least its first letter capitalized), if the application has a Name but not a Comment; otherwise the package name (because if you’re looking at a non-application package in the first place, you’re fairly likely to be the sort of user who wants to know the package name). <> [[#license|#]] The '''license label''' for an item should depend on the `License` field or fields in `debian/copyright`, and as a fallback, whether the package is in Main or Universe. For now, the label should be: * “Open source”, if it is in Main or Universe; * “Proprietary”, if it is in Restricted or archive.canonical.com; * “Unknown”, if it is anywhere else (including Multiverse and standalone packages). ''This license info should be [[Bug:435183|expanded]].'' ---- ''Work in progress'' The human-readable name for the `Perl` license keyword in `debian/copyright` should be “Perl license”, and for “`W3C`” should be “W3C license”. The human-readable name for any other license should be the first sentence in the “Meaning” column of [[http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/#license-specification|the table in Debian’s “Machine-readable copyright file” specification]] for that license, with any leading “The ” removed, any trailing period removed, and any version number rendered with a space instead of a dash. For example, the human-readable name for “`EFL-2`” should be “Eiffel Forum License 2.0” (not “Eiffel Forum License 2.0'''.'''” or “'''The''' Eiffel Forum License 2.0”). If all files in a package are covered by the same `License` field or by identical `License` fields, then: If there is only one license and it is OSI-approved, the license label should be “Open source ({human-readable name})”. If there are multiple licenses and they are all OSI-approved, the license label should be “Open source (various licenses)”. … * Open source (GNU General Public License 2.0) * Open source (various) * Open source * Various ---- <> == Searching for an application to open a file == The '''file type string''' for a file should start with its Mime type. If a human-readable name for this type is known, this should be followed by a space and then that human-readable name in brackets. For example, “model/vnd.gs-gdl”, or “image/jpeg (JPEG image)”. When asked to find an application to open an invalid filetype (e.g. “`unknown`”), Session``Installer should present an error alert, with title “Application Search”, primary text ‘Ubuntu can’t search for applications to open this file, because the file type is not recognized.’, and secondary text “File type: {file type string}”. {{attachment:search-invalid.png}} When asked to find an application to open a valid filetype, Session``Installer should open a progress window. {{attachment:search-progress.png}} If no applications are available, the progress window should morph into an error alert, with primary text ‘Sorry, no applications were found that could open “{filename}”.’, and secondary text “File type: {file type string}”. If any applications are available, the progress window should morph into a dialog asking you which application to install. {{attachment:search-choose.png}} If you select an application and choose “Install”, the dialog should morph into [[#general|the progress window for installation]]. <> == Data for other operations == Each operation should have: * '''Type''' — install, reinstall, update, remove, or purge. * '''UI mode''' — whether progress is displayed by the calling program, or whether Aptdaemon should display it in a separate window. * '''Status text''' — the current progress in human-readable form. * '''Progress''' — how much of the task is currently complete, as a fraction from 0 to 1 (or -1 if it is waiting for other tasks). * An optional '''window''' belonging to the program that requested the operation, so that any authentication or error alert can be made modal to that window. <> == General UI for all other operations == When any package operation is requested: 1. If the requesting program has not signalled that it provides its own progress UI (as [[SoftwareCenter|Ubuntu Software Center]] and [[SoftwareUpdates|Software Updater]] do, for example), a progress window should appear. Its title should represent the operation type: “Installing Software”, “Updating Software”, “Removing Software”, or “Purging Software”. The primary text should be the action followed by the name of the package: for example, “Installing google-chrome-stable”, or “Removing ”. If the operation is cancellable at any point (installing or updating), a “Cancel” button should be adjacent to the progress bar; it should become insensitive at the point where the operation is no longer cancellable.<
> {{attachment:progress-installing.png}} {{attachment:progress-removing.png}} 1. Session exit should be inhibited (bug Bug:842799). ''Can we customize the explanation the user sees if they try to log out?'' 1. If necessary, an [[AccountPrivileges#alert|authentication alert]] should appear modal to the progress window, blocking the operation until you authenticate. 1. If there are any tasks ahead of this one in the queue, the progress should be set to the waiting value, and status text set to “Waiting for other tasks to complete…”. 1. If `apt` (`/var/lib/apt/lists/lock`) or `dpkg` (`/var/lib/dpkg/lock`) is locked by something other than `aptdaemon` (`STATUS_WAITING_LOCK`) for more than 30 seconds, an alert should appear once, “{requesting application} can’t install or remove software until {locking program} exits.”, with “Cancel” and “Keep Waiting” buttons. “Cancel” should cancel the operation. If the lock is cleared while the alert is open, its buttons should become insensitive for two seconds, then it should close.<
> {{attachment:keep-waiting.png}} 1. If the `dpkg` binary cache is damaged, progress should be set to the waiting value, with status text “Repairing package cache…”, while the cache is repaired. 1. If there are any incomplete or failed installations, progress should be set to the waiting value, with status text “Repairing previous failed installations…”, while those tasks are recovered. If the repair fails, the progress window should morph into an error alert, with primary text ''[saying what?]'' and an “OK” button. 1. If the operation can’t be performed because of any other error that can be detected before changes are made, the progress window should morph into an error alert, with a “Details” section giving the technical error message (bug Bug:1063097). Once you dismiss the alert, the operation should cancel.<
>{{attachment:error-file-unreadable.png}} * If a file needed by `apt` is missing or unparseable, the alert should have primary text “Software can’t be installed or removed because an essential file is unreadable.”, and secondary text “No changes were made. To fix the problem, restore the file from backup, or reinstall Ubuntu.” (bug Bug:791715). * If there is not enough disk space, the primary text should be “Software can’t be installed or removed because there is not enough disk space.”, and secondary text “No changes were made. Deleting other unwanted files may free up enough disk space.” * If the operation requires reinstalling a package but the archive is missing, the primary text should be ‘The package “{name of package}” can’t be reinstalled because the archive is missing.’ and secondary text “No changes were made.”. * For any other error, the primary text should be “Software can’t be installed or removed because of an unknown error. Sorry about that.” and secondary text “No changes were made.”. 1. The task should be performed, as specified below: [[#installing|installing]], [[#reinstalling|reinstalling]], [[#updating|updating]], [[#removing|removing]], or [[#purging|purging]]. * Whenever the task involves downloading any software, the [[#operations|status text]] should be: * “Downloaded {amount} of {total} ({rate}, {period} remaining)” if the download rate is stable and the estimated time remaining is more than 30 seconds, for example “Downloaded 15.6 MB of 131.0 MB (20 KB/s, 6 minutes remaining)” (bug Bug:883625); * otherwise, “Downloaded {amount} of {total} ({rate})” if the download rate is stable and the estimated time remaining is 30 seconds or less, for example, “Downloaded 15.6 MB of 131.0 MB (24 MB/s)” (bug Bug:524690); * otherwise, just “Downloaded {amount} of {total}” (bug Bug:864134), for example, “Downloaded 15.6 MB of 131.0 MB (24 MB/s)”. * Whenever the task is interrupted by a debconf prompt, the status text should be “Waiting for your response…”. * In all other cases, the status text should be the latest line of the `dpkg` output. 1. Once the task completes (successfully or unsuccessfully), session exit should no longer be inhibited (unless there are further tasks waiting). 1. If the requesting program is no longer running (for example, Ubuntu Software Center which has since been closed), a notification bubble should appear (bug Bug:528584). The icon should be that of the software item. The title should be of the form “Installation complete”, “Reinstallation complete”, “Update complete”, “Removal complete”, or “Purge complete”. And the body text should be the item [[#title|title]]. <> If the operation fails after changes began, an error alert should appear with primary text ‘Sorry, “{title of item}” couldn’t be {installed/reinstalledupdated/removed} because an unknown error occurred.” (bug Bug:441686). For that, or any other, confirmation or error alert: ||<^ style="border:none">{{attachment:unknown-error-update.png}}<
>If a window was specified for the task, the alert should use, as its icon, the icon of the application that window belongs (or belonged) to. If the window is still open, the error alert should open modal to that window, and should not have its own title.||<^ style="border:none">{{attachment:unknown-error-remove.png}}<
>If a window was ''not'' specified for the task, the alert should use the standard error or confirmation icon. And if a window was not specified, ''or'' if it was but is no longer open, the error alert should have a title of the form “Installation Error”, “Update Error”, or “Removal Error”.|| <> == Installing software == When one or more package installations are requested: 1. If any of the packages conflict with installed packages, a confirmation alert should appear (bug Bug:704155): ‘“{[[#title|title]]}” can’t be installed unless these items are removed:’, or “This software can’t be installed unless these items are removed:”. Any affected applications, followed by any other affected packages, should be listed [[SoftwareCenter#def-alphabetically|alphabetically]] in an inset list that does not allow selection but is focused by default. The alert should have “Cancel” and “Remove & Install” buttons, with “Cancel” being the default. '''Test case:''' Install `notification-daemon` or `notify-osd`, whichever you don’t currently have installed.<
><
>{{attachment:install-conflict.png}} 1. The software should be installed. <> == Reinstalling software == ''TBD'' <> == Updating software == When one or more package updates are requested: 1. If any of the new package versions conflict with other installed packages, a confirmation alert should appear (bug Bug:430197): ‘“{[[#title|title]]}” can’t be updated unless these items are removed:’ or “These updates can’t be installed unless these items are removed:”. It should have “Cancel” and “Remove & Update” buttons, but otherwise be identical to [[#installing|the equivalent alert when installing a new package]]. 1. If the update suggests changing a configuration file, an alert should appear (bug Bug:1197727): {{attachment:config-change.png}}<
><
> The icon of the alert should be that of the calling application (for example Software Updater).<
><
> “Use the new version” should be the default selection.<
> The initial scroll position of both fields should be such that the location of the first difference between the old and new configuration files is visible. The “〈” and “〉” buttons should scroll both fields simultaneously to the location of the previous and next difference, respectively. “〈” should be insensitive when the last non-manual scroll was to the first difference (so it should be insensitive initially), and “〉” should be insensitive when the last non-manual scroll was to the final difference. 1. The updates should be installed. <> == Errors common to installations and updates == <> === Broken/unsatisfied dependencies === '''Test case:''' `sudo apt-get install 4g8 && sudo dpkg --force-depends -r libnet1`, then try to install anything. Afterwards, if necessary, use `sudo apt-get remove 4g8 libnet1` to recover. ||{{attachment:broken-dependencies.png}}|| If software can’t be installed because existing software has broken or unsatisfied dependencies, a confirmation alert should appear. It should have primary text “New software can’t be installed, because there is a problem with the software currently installed. Do you want to repair this problem now?” The secondary text should vary depend on whether fixing the problem requires downloading (not just installing, but downloading) software, and whether or how much software needs to be removed: || ||'''No software needs downloading'''||'''Software needs downloading'''|| ||'''No software removed'''||No software will be removed.||{size} extra will be downloaded. No software will be removed.|| ||'''Only non-application software removed'''||Repairing the problem requires removing some software.||Repairing the problem requires removing some software. {size} extra will also be downloaded.|| ||'''At least one graphical application removed'''||Repairing the problem requires removing {one of the applications} and {number of other packages} other items.||Repairing the problem requires removing {one of the applications} and {number of other packages} other items. {size} extra will also be downloaded.|| Following the secondary text, a “Details” pane — collapsed by default — should list the software that will be installed and removed, before “Cancel” and (default) “Repair” buttons. <> === Downloading fails === If, during an installation or update, a package fails to download (`ERROR_PACKAGE_DOWNLOAD_FAILED`), then: 1. If the computer is no longer connected to the Internet, an error alert should appear. It should have primary text “{[[#title|title]]} can’t be downloaded because there is no Internet connection.”, secondary text “Connect to the Internet and try again.”, and buttons “Cancel” and “Try Again”. If an Internet connection begins while the alert is open, its buttons should become insensitive for two seconds, then it should close itself and the download should start again automatically. {{attachment:package-download-failed-internet.png}} 1. Otherwise, if there is an Internet connection, the package list should be reloaded immediately. If that fails too, an error alert should appear. It should have primary text “{[[#title|title]]} can’t be downloaded because the software channel is not available.”, secondary text “Try again later.”, a secondary “Details” expander control that reveals a text frame containing the `libcurl` error message, and buttons “Cancel” and “Try Again”. {{attachment:package-download-failed-list.png}} 1. If the package list download succeeds, and the URL of the file has changed, the task should be tried again immediately. If it still fails, or if the URL of the file has not changed, an error alert should appear. It should have primary text “{[[#title|title]]} can’t be downloaded at the moment, because the software is missing from the server.”, secondary text “Tray again in a day or two.”, a secondary “Details” expander control that reveals a text frame containing the `dpkg` error, and buttons “Cancel” and “Try Again”. {{attachment:package-download-failed.png}} <> === Downloading the package list fails === If downloading the package list fails (`ERROR_REPO_DOWNLOAD_FAILED`), then: 1. If the computer is no longer connected to the Internet, an error alert should appear, with primary text “The software catalog can’t be updated because there is no Internet connection.”, secondary text “Connect to the Internet and try again.”, and buttons “Cancel” and “Try Again” (bug Bug:484466). If an Internet connection begins while the alert is open, it should close itself and the download should start again automatically. 1. Otherwise, an error alert should appear with primary text “The software catalog can’t be updated right now.”, secondary text any error from `apt`, and buttons “Cancel” and “Try Again”. <> == Removing software == When a package removal is requested: 1. If the relevant package is part of the `ubuntu-desktop` metapackage, a confirmation alert should appear: “{[[#title|title]]} is a core item in Ubuntu. Removing it may cause future upgrades to be incomplete.” The alert should have “Cancel” and “Remove Anyway” buttons; neither button should be the default. 1. If you request to remove a package that is part of any other metapackage, a confirmation alert should appear: ‘If you uninstall {[[#title|title]]}, future updates will not include new items in the “{metapackage [[#title|title]]}” set.’ Again, the alert should have “Cancel” and “Remove Anyway” buttons; neither button should be the default. 1. If you request to remove a package that is depended on by any other package, or an application that shares a binary package with any other application, a confirmation alert should appear: “To remove {[[#title|title]]}, these items must be removed as well:” — with any affected applications, followed by any other affected packages, listed [[SoftwareCenter#def-alphabetically|alphabetically]] in a list that does not allow selection but is focused by default. The alert should have “Cancel” and “Remove All” buttons; neither should be the default.<
><
>{{attachment:remove-depended-alert.jpg}} 1. If the item is represented in the Launcher, it should immediately disappear from the Launcher. 1. The package should be removed. == Purge ==