Documentation about upgrading to alr 2.x

UPGRADING.md

@@ -1,10 +1,41 @@
 ## Upgrading from 1.x to 2.x
 
+There are no special preparations to be made in advance to upgrading. However,
+please check out the following information.
+
+### Obsolete large folders
+
 Changes in default storage locations mean that the following folders, if
 existing, can be safely deleted to retrieve disk space:
 
-- <userdir>/.cache/alire
-- <userdir>/.config/alire/cache
+- `<userdir>/.cache/alire`
+- `<userdir>/.config/alire/cache`
 
 On Windows, `<userdir>` stands for `%UserProfile%`, whereas for other OSes it
 stands for `$HOME`.
+
+Also, `alr 2.x` defaults to shared builds, meaning that local workspace
+caches can also be removed at
+
+- `<crate>/alire/cache/dependencies`
+
+### New features in 2.x
+
+Please find all user-facing changes at our [User Changes log
+file](https://github.com/alire-project/alire/blob/master/doc/user-changes.md).
+
+## Downgrading to an earlier version
+
+This is not a recommended nor supported operation, as changes in storage of configuration and
+other resources may make a downgrade prone to failure.
+
+If you want to have a fallback to be able to downgrade, you have two safe
+options:
+
+- Use the newer version with its own separate configuration storage. You can override
+  the default location by providing a new path in the `ALR_CONFIG` environment
+  variable.
+
+- Keep a backup of your current configuration at the default location, which is
+  `.config/alire` within your user's home. You can restore this folder in sync with
+  its older `alr` version.

src/alr/alr-commands-topics-upgrading_alr.ads

@@ -0,0 +1,24 @@
+with AAA.Strings;
+
+with CLIC.Subcommand;
+
+package Alr.Commands.Topics.Upgrading_Alr is
+
+   type Topic is new CLIC.Subcommand.Help_Topic with null record;
+
+   overriding
+   function Name (This : Topic) return CLIC.Subcommand.Identifier
+   is ("upgrading_alr");
+
+   overriding
+   function Title (This : Topic) return String
+   is ("Notes on upgrading between major `alr` versions");
+
+   overriding
+   function Content (This : Topic) return AAA.Strings.Vector
+   is (AAA.Strings.Empty_Vector
+       .Append ("For up-to-date information, please visit:")
+       .Append
+         ("https://github.com/alire-project/alire/blob/master/UPGRADING.md"));
+
+end Alr.Commands.Topics.Upgrading_Alr;

src/alr/alr-commands.adb

@@ -43,9 +43,10 @@ with Alr.Commands.Update;
 with Alr.Commands.Version;
 with Alr.Commands.Withing;
 
+with Alr.Commands.Topics.Aliases;
 with Alr.Commands.Topics.Naming_Convention;
 with Alr.Commands.Topics.Toolchains;
-with Alr.Commands.Topics.Aliases;
+with Alr.Commands.Topics.Upgrading_Alr;
 
 with GNAT.OS_Lib;
 
@@ -660,8 +661,9 @@ begin
    Sub_Cmd.Register ("Testing", new Test.Command);
 
    -- Help topics --
+   Sub_Cmd.Register (new Topics.Aliases.Topic);
    Sub_Cmd.Register (new Topics.Naming_Convention.Topic);
    Sub_Cmd.Register (new Topics.Toolchains.Topic);
-   Sub_Cmd.Register (new Topics.Aliases.Topic);
+   Sub_Cmd.Register (new Topics.Upgrading_Alr.Topic);
 
 end Alr.Commands;