From c25dd5465e41b289c28cefe70886d225ccfcc000 Mon Sep 17 00:00:00 2001
From: Alejandro R Mosteo <amosteo@unizar.es>
Date: Mon, 29 Jan 2024 12:15:57 +0100
Subject: [PATCH] Documentation about upgrading to alr 2.x (#1547)

---
 UPGRADING.md                                  | 35 +++++++++++++++++--
 src/alr/alr-commands-topics-upgrading_alr.ads | 24 +++++++++++++
 src/alr/alr-commands.adb                      |  6 ++--
 3 files changed, 61 insertions(+), 4 deletions(-)
 create mode 100644 src/alr/alr-commands-topics-upgrading_alr.ads

diff --git a/UPGRADING.md b/UPGRADING.md
index bd02e956..1020de0b 100644
--- a/UPGRADING.md
+++ b/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.
\ No newline at end of file
diff --git a/src/alr/alr-commands-topics-upgrading_alr.ads b/src/alr/alr-commands-topics-upgrading_alr.ads
new file mode 100644
index 00000000..110cf63c
--- /dev/null
+++ b/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;
diff --git a/src/alr/alr-commands.adb b/src/alr/alr-commands.adb
index c8954f81..384b9064 100644
--- a/src/alr/alr-commands.adb
+++ b/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;
-- 
2.39.5