Skip to content
This repository has been archived by the owner on Jan 6, 2023. It is now read-only.

Format Bumps

Jump to bottom
Patrick McCarty edited this page Mar 1, 2018 · 7 revisions

Introduction

The SWUPD project permits a distro builder to introduce breaking changes to the OS; the breaking changes could be for SWUPD (client and/or server) itself, or any other changes of behavior in the distro that are impossible or difficult to solve by keeping backward compatibility with previous behavior. A breaking change of this nature is implemented through a SWUPD format change (also called a format bump). SWUPD formats are represented by positive integers and are incremented whenever a format change is deployed.

More details about how this feature relates to using the Clear Linux mixer can be found in the "OS Epoch or Format version" section of the Clear Linux Mixer documentation. Also see Format-bump-rationale.

The following process describes how format bumps operate, without tying the details to the Clear Linux mixer.

Example Format Bump Process

First, we introduce some terminology used in the process steps.

Terms

  • +10 version: the next build of the distro, assuming the distro versions increment by 10.
  • +20 version: the build after the +10 version build, as described above.
  • formatN: the current format number, prior to a new format being introduced.
  • formatN+1: the new format number, introduced in the +20 version.
  • format-compatible: version pairs of SWUPD client and server that understand the same format.
  • bundle: a collection of files to be installed as a unit.
  • bundle chroot: a directory hierarchy with installed bundle contents.
  • update content: SWUPD collateral produced by swupd-server, to be later consumed by swupd-client.
  • WEBDIR: the location where SWUPD update content is published and exposed via a web server.

Process steps

  1. Incorporate relevant breaking changes into the build system. For example, if there are breaking changes to be introduced for SWUPD, a swupd-server and/or swupd-client release is incorporated. Note that swupd-server and swupd-client must be format-compatible.
  2. Create bundle chroots for a +20 version. Set /usr/share/defaults/swupd/format to formatN+1 in the bundle containing swupd-client.
  3. Create update content for the +20 version, with formatN+1 passed to swupd_create_update.
  4. Duplicate bundle chroots from the +20 version for the +10 version.
  5. Create update content for the +10 version, with the previous release of swupd-server, and with formatN passed to swupd_create_update.

Publishing the two builds

  1. Set WEBDIR/version/formatN/latest contents to the +10 version. Note that the value must be frozen after this point, since it is the last version a swupd-client understanding formatN can possibly update to.
  2. Set WEBDIR/version/formatN+1/latest contents to the +20 version.
Clone this wiki locally