Add info about offline upgrades between major versions

Described the switching between ostree branches (aka "upgrade
major version") during offline upgrades.

Signed-off-by: Denis Pynkin <denis.pynkin@collabora.com>

content/designs/system-updates-and-rollback.md

@@ -10,12 +10,8 @@ aliases = [
 ]
 outputs = [ "html", "pdf-in",]
 date = "2016-05-28"
+lastmod= "2020-12-17"
 +++
-
-# System updates and rollback
-
-##  Introduction
-
 This document focuses on the system update mechanism, but also partly addresses
 applications and how they interact with it.
 
@@ -461,6 +457,45 @@ the expense of a potential increase of the requirements on the mass storage
 device used to ship them. Both partial and full deltas leading to the same
 OSTree commit will produce identical results on the devices.
 
+#### Switching to the new branch
+
+The branches naming schema used in Apertis contains the major version, for instance:
+`apertis/v2020/armhf-uboot/minimal`. So for Apertis the "major upgrade" is technically
+considered as switching to another branch with a more recent Apertis version, for
+example `apertis/v2021/armhf-uboot/minimal`. By default such kinds of offline upgrade
+with switching to another branch is restricted by update manager.
+
+Offline upgrades between branches (including "major updates") consists of 2 steps which
+should be a part of offline upgrade:
+
+1. Prepare the proper commit at build time
+
+   This step is pretty simple -- while preparing the relevant commit we
+   just need to add the branch name(s) from which we are supposed to be able to upgrade to the
+   current version. For example, while preparing commit for `v2021` version just
+   add following into `ostree-commit` action:
+   ```
+   ref-binding:
+     - apertis/v2021/{{$architecture}}-{{$board}}/{{$type}}
+     - apertis/v2020/{{$architecture}}-{{$board}}/{{$type}}
+   ```
+   this produce the commit compatible with version `v2020` allowing to install the
+   new OS version `v2021` onto the board.
+
+2. Set correct refs in repository
+
+   After successful boot of the updated version all refs in `libostree` repository
+   are still pointing to the previous branch due the nature of offline upgrade.
+
+   This needs to be fixed for proper detection of further upgrades, including updates
+   over the air. It is the responsibility of the update manager to update the refs 
+   once the update has been determined to be successful.
+
+This functionality requires no changes to be made to previously released OSTree versions.
+The configuration that determines upgrade paths is held in the newer OSTree commit.
+
+Apertis currently only supports upgrades to newer versions, downgrades to older versions
+of Apertis are not supported. 
 
 ### OSTree security
 
@@ -590,6 +625,19 @@ ostree config set core.sign-verify-deltas "true"
 ```
 This is forcing AUM and `libostree` to accept only update bundles with signed metadata.
 
+##### Compatibility with upgrades
+
+Until `v2021pre` there were no support of upgrade bundles with signed metadata in Apertis.
+
+For upgrading from version `v2020` to `v2021` we have produced additional upgrade bundle.
+This additional bundle has unsigned metadata, allowing offline upgrades from the previous
+release. So for `v2021`, and only for `v2021` we have 3 update bundle types:
+- `*.delta` -- depending on CI it may have signed or unsigned metadata.
+  This version is uploaded into Hawkbit server and used for tests.
+- `*.delta.enc` -- encrypted bundle containing delta file above.
+- `*.compat-v2020.delta` -- bundle with unsigned metadata compatible with previous
+  Apertis release. This file should be used for upgrading the Apertis version `v2020`.
+
 #### Securing OSTree updates download
 
 OStree supports "pinned TLS". Pinning consist of storing the public key of the
@@ -779,7 +827,7 @@ blacklist and then drops them.
 
 ### The updater daemon
 
-The upgrader daemon is responsible for most of the activities involved, such as
+The updater daemon is responsible for most of the activities involved, such as
 detecting available updates, initiating the update process and managing the
 boot count.
 
@@ -844,9 +892,17 @@ is detected. This is to avoid transient issues causing an unwanted rollback
 which may make the situation worse.
 
 To do so, the boot counting is stopped once the current boot is considered
-succesful, effectively marking the current boot as known-good without the need
+successful, effectively marking the current boot as known-good without the need
 to maintain a whitelist and synchronize it with the bootloader.
 
+As a part of marking the deployment as successful the updater daemon checks the
+target branches from the OSTree commit metadata. If the booted deployment contains
+references to several branches, the updater daemon determines which branch has the highest
+version and resets all refs and the origin to that branch. Using the branches naming scheme
+used in Apertis, this could be considered as "major upgrade" of the system.
+From this point on, the system is fully switched to the new branch and accepts
+only upgrades created in the new branch.
+
 ### Command line HMI
 
 A command line tool is provided to query the status using