AOSC Wiki / Developer / Packaging / .

AOSC OS Topic-Based Maintenance Guidelines

General Procedural Guidelines for AOSC OS Package Maintenance

Introduction

Effective Fall 2020, AOSC OS ends its use of seasonal iteration cycles, and moves to a new iteration schedule based on "topics." A topic in this case refers to "campaigns" in which one or more packges updated, rebuilt, or changed.

Rationale

This change is made in response to the increasing challenge for maintainers to keep up with iteration cycles, and its various shortcomings. For instance, although our Spring 2020 iteration cycle was completed on time, it came at a cost of reduced work (or accomplishments, to put it bluntly). New packages are also forced to go through testing-proposed, testing, and finally landing in stable on a cyclic schedule, it takes at least three months to reach stable users. Furthermore, our current system of Exceptions, updates are not sufficiently tested, as dependencies of Exceptions are also allowed to be updated on the same exceptional basis.

An Illustrated Comparison

Topic-based iterations deprecates the current six-branch architecture as described in our old AOSC OS Maintenance Guidelines, and instead considers each update (e.g. GNU Nano 5.4) or wave of updates (KDE Applications 20.08) a "topic," each maintaining its own build-test-ship pipeline.

For instance, to update KDE Applications 20.04 to 20.08, in the old iteration cycle, it goes as follows:

ProcedureWorkTime Frame
SurveyMaintainer finds KDE Applications 20.08 update, reads changelog and announcementNon-Freezing Period (~2 Months)
PackagingMaintainer packages KDE Applications 20.08, commits changes to testing-proposedNon-Freezing Period (~2 Months)
TestingMaintainer pushes package to repository for testingUntil End of Cycle (~3 Months)
ShippingMaintainer merges branches and moves packages to stable for general adoptionEnd of Cycle (~3 Months)

In the new system, instead of a set three-month (or often times longer) iteration, in which other packages are mixed in with KDE Applications 20.08, the procedures goes as follows (with assumed time requirement):

ProcedureWorkTime Frame
SurveyMaintainer finds KDE Applications 20.08 update, reads changelog and announcementDay of Update Discovery (Day 1)
DiscussionMaintainer discusses the suitability of said updates with other maintainersDay of Consensus Reached (Day 3)
PackagingMaintainer creates a topic branch kde-applications-20.08 and packages updatesDay of Build Completion (Day 7)
TestingMaintainer pushes KDE Applications 20.08 to a kde-applications-20.08 repositoryDay of Build Completion (Day 7)
NotificationMaintainer notifies other maintainers and users of such repository, opens a Pull Request for auditionUntil Approval (Day 14)
ShippingMainatiner merges kde-applications-20.08 into stable, rebuilds all packages against stable, uploading rebuilt packages to stable for general adoptionDay of Second Build Completion (Day 16)

In this sense, KDE Applications 20.08 could be surveyed, discussed, packaged, tested, and shipped according to its own time requirement. As KDE Applications are (supposedly) used by many, testing could be done in a relatively short period of time, massively shortening the old (up to) 3-month aging period.

This procedure will be discussed in detail in the subsequent sections.

Definitions, Rules, and Procedures

This section denotes conceptual definitions, rules, and procedures for maintainers.

Definitions

A "topic" is an act of updating, rebuilding, and changing one or more packages. In each topic, only a minimal set of package(s) affected is included. Each topic is a self-contained (and thus independent [from other topics]) cycle of surveying, discussion, packaging, testing, notification, and shipping.

Rules

  1. A topic is to be as specific as possible, only including the exact package intended for update, rebuild, or change.
    • The only exception to this is when multiple packages "naturally belong" or "could be reasonably bundled together." Generally, a wave of updates to a desktop environment (GNOME 3.38; Plasma 5.20), similar packages (various RIME data packages), or packages whose updates trigger rebuilds (Boost 1.73) falls under this exception.
  2. A topic, once complete, is never to be re-used.
  3. A topic should never conflict or cast influence on another in such a way that requires a rebase.
    • Prior to creating a topic, maintainers should discuss with others during daily communication or weekly meetings to work out possible inter-topic conflicts.
    • Once potential conflict(s) is found, maintainers should discuss among themselves to delay one or more topics as necessary.
    • If a conflict were accidentally created, then maintainers should work out a plan to rebase one branch against another.
  4. A topic should be named in the format of $PKGNAME-$PKGVER (e.g., nano-5.4). Repository branch naming follows topic name (e.g., nano-5.4).
    • Non-update topics should be named by purpose, in the format of $PKGNAME-$PKGVER-$PURPOSE (e.g. gnome-shell-3.38.1-build-fix, gnome-shell-3.38.1-ppc64el-adaptation; in case a packge is being introduced, use gnome-shell-ng-4.0-new).
    • In case of multi-package topics, topics takes name from the "main player" along with its general version, e.g. gnome-3.38, boost-1.73.
    • In multi-package, multi-version topics, use main package name, followed by "-survey", and date of update survey, e.g. rime-data-survey-20200928.
  5. When building packages for a topic, a clean environment is required for each package. This means rolling back each environment to a bare BuildKit, before building the next.
    • There is no exception to this rule.
  6. Open a Pull Request for review. Maintainers are directed to test affected packages, users are also notified via a topic manager installed on their AOSC OS deployment.
    • When testing is done, merge pull request.
    • A tag is then created, and the working branch deleted.
    • Rebuild all affected package(s) against a stable environment before uploading to the stable repository. Old scratch builds are archived.
  7. Testing cycles are indefinitely long, but a package, once tested in each respective architecture, they are green-lit and a topic is then marked "done."
    • Stale cycles are great evidence for unmaintainable package, drop them.
    • Never merge package due to staleness.

Topic Cycles

A topic-based iteration cycle follows these general steps:

Stable Branch Protection

The stable branch is protected and no direct commit would be allowed. All commits should only be merged into this branch following the rules and procedures described above.

Special Topics and Exceptions

There are a few topics that requires further clarification, or exceptions applied to their procedures. This section describes such cases.

Release Candidate Kernels

Traditionally, AOSC OS packages Release Candidate kernels to give maintainers a head start on configuration and patch adaptation. However, such maintenance is a longer process than most topics, usually spanning the whole RC phase (2 - 3 months).

Thankfully, there is no package conflict possible with other topics, since this topic should only affect these two packages:

The following rules and procedures apply for this case:

New Port Bring-Ups

In case a new port is being brought up (building packages for the first time for a new port), all rules above still applies (one package per topic for port adoption). However, to make porters' and other maintainers' lives easier, the following exceptions are granted:

Planned Rebuilds

In case of planned rebuilds, which are done in order to refresh stale packages. During these planned rebuilds, it is anticipated that a large set of packages will be built at once. The following exceptions are therefore granted to this scenario:

Planned rebuild topics should be named planned-rebuild-$DATE, e.g. planned-rebuild-20201225.

AOSC OS/Retro

The topic-based procedures and rules does not apply to AOSC OS/Retro. Updates are synchronised from the stable branch annually, and all security and bugfix changes are committed directly to the retro branch.

Inter-Operability with Mainline

After each synchronisation (or merge) from the stable branch, a Pull Request is created against the stable branch as a retro-tracking-$YEAR topic. Follow all procedures and rules above.

Documentation

Changes Required Following This Change

With the transition to topic-based iterations, changes are required in the following documents:

Deprecated By This Change

With the transition to topic-based iterations, the following documents will be deprecated: