RFC: Specification for Topic Update Manifest

topic-update-metadata.md

Overview

The topic update manifest aims to provide a user-readable overview of changes during system updates. The files are stored in the TOML format in the ABBS tree and converted into the JSON format on the server-side.

Examples

Below is an example for a conventional topic update manifest file.

name.default = "KDE Updates (Winter 2023)"
name.zh_CN = "KDE 更新（2023 年冬季）"
# Security update (true/false)?
security = true
# OPTIONAL: PSA message for users.
caution.default = """
This topic may use significantly more memory after reboot. Our testing finds
that the new KDE version may use up to 16GiB of RAM.
"""
caution.zh_CN = """
本次更新重启后可能会需要更多内存。据我社维护者测试，新版 KDE 可能需要接近 16GiB 内存。"""

[packages]
konsole = "23.04.1-1"
dolphin = "23.04.1"
# Package removed as part of the topic.
pykde = false

Below is a "cumulative" topic update manifest file.

name.default = "Winter 2023 Cumulative Update for amd64 AOSC OS systems"
name.zh_MS = "适用于 amd64 AOSC OS 版本的 23 冬季累计更新"

# Must not exist alongside [packages].
topics = [
    "kde-survey-20231201",
    "core-12.1.0"
]

Files

Topic update manifest files will be stored in a special topics/ folder in an ABBS tree.

TREE/topics/kde-survey-20231201.toml
TREE/topics/llvm-16.0.6.toml
TREE/topics/*.toml

The repository server will pull the ABBS tree periodically, processing the manifest files into a single, compressed JSON.

*.toml => (server pulls tree during mirrorupdate.service) => /mirror/debs/manifest/updates.json

A sample post-processed JSON file should look like this:

{
        "kde-survey-20231201": {
                "type": "conventional",
                "name": [
                        { "default": "KDE Updates (Winter 2023)" },
                        { "zh_CN": "KDE 更新（2023 年冬季）" }
                ],
                "security": true,
                "caution": [
                        { "default": "This topic may use significantly more memory after reboot. Our testing finds\nthat the new KDE version may use up to 16GiB of RAM." },
                        { "zh_CN": "本次更新重启后可能会需要更多内存。据我社维护者测试，新版 KDE 可能需要接近 16GiB 内存。" }
                ],
                "packages": [
                        { "name": "konsole", "version": "23.04.1-1" },
                        { "name": "dolphin", "version": "23.04.1" },
                        { "name": "pykde", "version": null }
                ]
        },
        "cumulative-2023H3": {
                "type": "cumulative",
                "name": [
                        { "default": "Winter 2023 Cumulative Update for amd64 AOSC OS systems" },
                        { "zh_MS": "适用于 amd64 AOSC OS 版本的 23 冬季累计更新" }
                ],
                "topics": [
                        "kde-survey-20231201",
                        "core-12.1.0"
                ]
        }
}

Scope

Procedural Changes

• Add toml review as part of the topic review procedure.
• Require a topic toml if pull request is of "survey" type, optional otherwise.
• CI to lint toml files (.lint-topics-toml.json in the root of the tree).

Tooling Changes

• Script to generate list of affected packages.
• ACBS: Ignore topics/.
• Server-side (repokit): Script to pull manifest files from aosc-os-abbs, concatenate into updates.json, compress.
  • Run this procedure during mirrorupdate.service.

Omakase Changes

• Only change oma upgrade behaviour.
• If no packages were removed: Display only a list of update topics, directly on the console ...

System Update(s) Available # Highlighted in blue background and white text.

Omakase has found the following updates are available for your system:

  Name                                         |  Package(s) affected
------------------------------------------------------------------------------
  KDE Updates (Winter 2023)                    |  127 updated, 2 new packages
  AOSC OS Core 12.0.2                          |  7 updated

A total of 127 package(s) will be updated, 2 new package(s) will be installed.

Would you like to proceed with the system update? (yes/no/review)

• If packages were to be removed: Use the old "less" interface, with a list of topics listed atop ...

System Update(s) Available # Highlighted in blue background and white text.

Omakase has found the following updates are available for your system:

  Name                                         |  Package(s) affected
------------------------------------------------------------------------------
  KDE Updates (Winter 2023)                    |  127 updated, 2 removed
  AOSC OS Core 12.0.2                          |  7 updated

A total of 127 package(s) will be updated, 2 new package(s) will be installed.

  Name                 |  Size                 |  Detail
------------------------------------------------------------------------------
  pykde                |  -114.00 KiB          |

Press [q] to end review, [Ctrl-c] to abort, [PgUp/Dn] or arrow keys to scroll

--- User hits [q] ---

Would you like to proceed with the system update? (yes/no/review)

• Possibly sync this behaviour for all oma operations ...

--- User hits [q] ---

Would you like to proceed with the system update? (yes/no/review)