AOSC OS Maintenance Guidelines (RFC)
General Procedural Guidlelines for AOSC OS Package Maintenance
AOSC OS is a multi-branch, seasonal rolling Linux distribution available with over 5,000 packages for multiple microprocessor architectures. As such, maintaining AOSC OS is not a trivial task, and all maintainers should work in accordance to a written guideline to avoid confusion and (the resulting) inconsistent quality.
The Branches, Cycles, and Ports
The concepts of branches, cycles, and ports are three main aspects that maintenance work revolves around. In this section, we will defines these concepts in the scope of AOSC OS.
AOSC OS is maintained concurrently across four branches:
- Stable (
stable): The main maintenance branch which most users should be using, updates include security updates, bug fixes, exceptional updates and patch-level updates.
- Stable, Proposed Updates (
stable-proposed): The branch that feeds said updates into
stable, unless the current
stablealready requires bug fixes (for instance, a currently available
stablepackage has broken dependency).
- Stable, Proposed Updates (
- Testing (
testing): The main feature branch which users with particular interest in following the latest development and changes should be using, security updates, feature/major updates, and new packages are introduced from the
explosivebranch and tested minimally before shipping. Updates made available through this branch will be available for
stableby the end of each update cycle.
- Testing, Proposed Updates (
explosive): The branch that feeds said updates into
testing, packages are introduced and build-time tested. No one should be using this branch, no matter what.
- Testing, Proposed Updates (
AOSC OS is maintained on an seasonal cycle, and thus revolves around a three-month schedule:
- The first two months - or the development period:
- Iteration Plans (e.g. the Iteration Plan for Summer 2019)are drafted and published on GitHub as a milestone issue, and updated frequently by maintainers as new updates are made available and built.
- Updates are built on all branches and for all ports when applicable.
- The last month - or the freezing period:
explosivebranches continues to receive updates as usual.
testingbranch will no longer accept updates unless they are intended for security or bug fixes.
testingbranch updates will be tested in preparation to become the new basis of
AOSC OS is available for many different microprocessor architectures (and thus many different kinds of devices). While some ports will received full-feature packages, there are distinctions based on the nature of the ports. Here below is a brief description:
- AMD64, or x86_64 (
amd64), the de facto main port.
- All packages will be build-time tested for this architecture.
- This is the only architecture to build
explosiveupdates as a preliminary procedure.
- AArch64 (
arm64), ARMv7 (
armel), Little Endian POWER (
ppc64el), and RISC-V (
- All packages should be built for these architectures unless non-applicable or unbuildable.
- These architectures do not track the
- Big Endian PowerPC 32/64-bit (
ppc64, respectively), and i586 (
- These architectures are considered part of the "AOSC OS/Retro" project, and do not follow all the rules specified so far.
- These architectures only track the
stablebranch, with a limited selection of packages deemed usable on older hardware.
This section describes the detailed procedures, which AOSC OS maintainers should adhere to.
The standard set of tools should be used by all maintainers. While we are unable to track the tools you've used (yet), these set of tools are known to generate the cleanest and most reproducible packages so far.
- Autobuild3, the package generation tool which abstracts building procedures and package metadata into Autobuild3 manifests.
- ACBS, organises and manages multiple Autobuild3 manifests in a tree-like fashion, see aosc-os-abbs.
- Ciel, manages
systemd-nspawncontainers where packaging work are done, with tools for Autobuild3/ACBS configuration, basic containerised environment management (updates and some configuration), and environment rollbacks.
- pushpkg, a simple wrapper script for uploading packages to the Community Repository.
You will also need a LDAP identity to upload packages and to gain access to our relay servers, or Buildbots.
While you are welcome to use your own devices for packaging (given that you are using the tools above), there are fast machines provided by community members, and made available for maintainers.
For more details on gaining access and the various protocols, please refer to the AOSC Buildbot Information.
Package Introduction and Maintenance
In principle, AOSC OS accepts and maintains all packages, unless one of the following applies:
- The vendor or upstream does not permit redistribution, or file manipulation (if required or mandated by the Styling Manual).
- The vendor or upstream refuses or failed to provide fixes for security vulnerability(ies).
- The package is deprecated by the vendor or upstream.
- The maintainers have voted against the introduction or continued maintenance of a specific (set of) package(s).
While building packages, the build environments must be controlled, updated, and minimal, where packages are only installed as required by the build-and-run-time dependencies.
- For instance, when building for
stable, make sure that only the
stablebranch is enabled in your repository configuration;
stableare enabled when building for
- There is an exception when building for
stable-proposed, only the
stablebranch should be enabled.
In the AOSC OS maintenance procedures, branch mergings are bi-directional.
With the branch and cycle descriptions specified above - as branch merging serves as the main mean of update introduction for the non-Proposal branches, there are certain limitations applied to the merging procedures.
- During the two-month development periods, the branch merging follows the direction of:
- During the one-month freezing periods: the
stablemerges are permitted, while all other mergings are not permitted.
Reversed merges, or
explosive merges should be done periodically regardless of the cycle periods. However, during major merges, notifications will be made to prevent inconsistent merging.
Stable Update Testing
Updates for the
stable branch, unless known to be involved with one or more 0-day security vulnerability(ies) or already broken in
stable, are committed, built, and tested through the
stable-proposed updates are merged in the following procedure/schedule:
- Every Saturday at midnight, UTC: An issue is generated with a comprehensive list of updates committed and bulit on the
- Package names, version deltas (e.g. 1.0.2 → 1.0.3), and changelogs (linked to specific AOSC OS Packages pages).
- Checkboxes by each entry.
- Testing procedures are defined case-by-case.
- TODO: Autobuild3/ACBS automatic quality assurance and reports.
- Basic functionalities (Launches? Comes with necessary files? Documentation readable and complete?).
- Styling checked against the Styling Manual.
- Packages, when tested, will have their respective entry(s) ticked, and packages moved on the repository from the
stable-proposedpool to the
stablepool on the package unit (one package "ticked", one moved).
- The weekly issues will remain open for tracking testing work, and closed upon full completion (all checkboxes ticked).