What does `do-release-upgrade` really do?

Solution 1:

do-release-upgrade is part of the package “update-manager-core”. The script seems to determine which release you are going to upgrade to, try to find out if it’s supported or not and complain about the latter. – If it’s convinced to work, it downloads the release-specific UpgradeTool and runs it.

Part of the “update-manager-core” package is the file /etc/update-manager/meta-release, where you can find the URL http://changelogs.ubuntu.com/meta-release and there you find the URL for the UpgradeTool to download.

The downloaded UpgradeTool tarball is packaged from the source package “ubuntu-release-upgrader” (before it was “update-manager”). The version corresponds to the latest updates for the target release.

The source has an old README from warty and hoary release times. It discusses what should be done during a release upgrade. It also mentions a link to a more detailed UpgradeTool proposal.

I list here the actions mentioned there and checked if they are actually implemented:

• repository related
  • switch to new sources.list entries
  • remove unknown 3rd party repositories
  • possibly swap mirror (not implemented)
• package related
  • check there are no broken packages before upgrading
  • update current release before upgrading (apt-get update only)
  • remove and install specific packages
  • check if {ubuntu,kubuntu,edubuntu}-desktop is installed
  • get rid of old kernels
  • have a removal-blacklist and -whitelist
  • remove or replace obsolete packages which existed in earlier releases
• configuration related (possible in quirks: see below)
  • adding the default user to new groups (not done for the versions I checked)
  • check some config files

The UpgradeTool is configured for each release using the following files (open them to see!):

• DistUpgrade.cfg
  • UpgradeTool-related configuration
  • release-related configuration
  • repositories (e.g. [Sources] ValidMirrors)
  • custom changes ([Distro] PostInstallScript)
  • special packages; processed only by DistUpgradeController.py:
    • [Distro] RemoveObsoletes, ForcedObsoletes, BaseMetaPkgs, MetaPkgs
    • [meta_package_name] ForcedObsoletes
  • ...and by DistUpgradeCache.py:
    • [Distro] MetaPkgs, RemovalBlacklist, RemoveEssentialOk, BadVersions, BaseMetaPkgs, PurgeObsoletes, Demotions, KeyDependencies
    • [Distro and meta_package_name] KeepInstalledPkgs, KeepInstalledSection, PostUpgrade*
    • [KernelRemoval] *
• DistUpgradeQuirks.py
  • runs (release) specific functions (same file) and plugins (plugins directory)
  • functions must have specific names (e.g. from_nattyPreCacheOpen()) and plugins special condition attributes (e.g. * or PostInitialUpdate)
  • one of those functions, StartUpgrade(), is another grab-bag itself: among others it calls _applyPatches(), which goes over the files in the patches directory
  • all these do pretty much nothing on my installation (i386, packages not older than natty-updates)
• more from DistUpgradeCache.py
  • runs get_kernel_list.sh (not in trusty) and makes sure one kernel is installed
  • some handling about Nvidia drivers

Checked versions:

• natty → oneiric
• oneiric → precise
• precise → trusty (final as of 2014-04-18)
• trusty → utopic (hours before release on 2014-10-23)