0009: New main device category

Summary

Move all QEMU-devices out of the “main” category to “community”.

Set new requirements for the “main” device category to highlight selected device ports which are well-tested in hardware CI and set up to stay in “main” for a long time through strong maintainership.

Change the meaning of the “main” category to not only indicate that more features are working than in the “community” category, but also that the postmarketOS team is highly invested in keeping the device in the “main” category and takes on responsibilities to make this likely.

Maintainers of devices in other categories are welcome to use some of these new requirements for “main” as blueprint for their devices as well, in order to get similar reliability and maintainership improvements for their devices.

Out-Of-Scope

The following topics are intentionally omitted from this PMCR:

  • Hardware CI cost reimbursement, see dpo!46 / expenditure policy for that.

  • Helping people with setting up hardware CI. The reference place for that is currently the hardware-ci chat.

  • A detailed description of device-$vendor-$codename.md and where in pmaports it is located.

  • A process for endorsing a new device for main, let’s define this separately as follow-up.

Motivation

The “main” category of devices is almost empty. It contains QEMU ports but no “real” devices since the v24.12 release where we moved the PinePhone and Librem 5 from main to community. As it was noted at the time, “this could be a good opportunity to set better standards for main, such as requiring an automated hardware test setup that could really ensure that we don’t introduce most regressions or at least notice them shortly afterwards and can fix them more easily.”

QEMU

We will set a lot of new requirements below for the “main” category that the QEMU devices currently do not meet, so move them from “main” to “community”. Furthermore we will likely just remove the QEMU devices in the future and boot the generic device packages (device-generic-x86_64 etc.) in QEMU instead.

Reliability

As of now the requirements for the “main” device category are mostly “working device features”, which historically comes from the difficulties we have had with making device features working at all with mainline Linux. Today we have many ports where the functionality is there, most device features can work under the right conditions. This is a huge achievement and was made possible by countless great contributors who improved postmarketOS, the Linux kernel and many userspace components such as ModemManager, libcamera, PipeWire, the user interfaces, etc.

It is now time that we turn these functional features into reliable features and have the new “main” category reflect that goal. Any future device in “main” should not only have functional features, but also have the infrastructure to continuously demonstrate that these are working reliably.

Stronger maintainership

The other motivation for this PMCR is to strengthen the maintainership of devices in the “main” category. With previous requirements we have seen:

  • Maintainer burn-out after the initial move to higher device categories.

  • Patches not getting merged, thus development stalling.

  • Having to quickly remove the device from this category again (or if not followed correctly, the device still being in main without actually having the maintainers requirement fulfilled anymore).

Consequences

  • Confusion about how reliable various device ports will be resolved: if it is in “main” then you can see through automated hardware CI test results that are available online, that a specific featureset works reliably.

  • Upstream components will benefit as we can find regressions quickly with automated testing and report them, and ideally try to get them fixed before they make it into a new release.

  • The Linux (Mobile) ecosystem will benefit in general from these efforts, once a device port works reliable in one distribution it is much easier to get it working reliably in other distributions as well.

Draft implementation plan

  1. QEMU devices

1.1 Move all QEMU devices from “main” to the “community” device category.

  1. Update the “main” section of the device categorization page as follows. Find old, new and rationale sections below.

Old:

Requirements:
* Maintained by >= 2 people
* Working device features (where available):
  * Usable phone UI (i.e. Plasma Mobile or Phosh)
  * Calls (incl. call audio with earpiece)
  * SMS
  * Mobile Data
  * WiFi
  * Audio (speaker, main microphone ; headset, headset microphone ; jack
    detection, headset buttons)
  * Battery charging
  * Bluetooth
* Everything from community (see below)

Not required yet (shall change in the future):

* Camera

New:

Requirements:
* The [postmarketOS team](https://postmarketos.org/team) must endorse the new
  device.
* A device maintainer team of at least 5 people, of which the majority are
  part of the [postmarketOS team](https://postmarketos.org/team).
* The postmarketOS team and device maintainer teams must cover their
  responsibilities as listed below. Within the teams, they must figure out
  themselves who covers what responsibilities.
* Hardware CI in at least two locations for (in total) at least 3 devices.
* Boot via UEFI.
* Must use
  [generic postmarketOS kernels](https://docs.postmarketos.org/pmaports/main/generic-kernels.html)
* Must not depend on forked device-specific packages, such as `alsa-ucm-conf`.
* Must use a generic device package for the target architecture.
* Everything from community (see below).

Responsibilities for the postmarketOS team:
* Regularly checking if requirements are still fulfilled, and if not:
  * Discuss with the device maintainers team.
  * Make calls for help early to e.g. find new members for the device
    maintainers team.
* Remove the device from main after 6 months of having the requirements
  unfulfilled.

Responsibilities for the device maintainer team:
* `device-$vendor-$codename.md`:
  * Maintain a file inside pmaports that
    explains what features are working, and which ones are not.
  * The working features should allow to use the device in most common use
    cases. A phone for example would typically have calls, SMS, mobile data,
    Wi-Fi, audio, battery charging, Bluetooth and camera. Exceptions can be
    made by the device maintainer team, together with reasoning why they are
    necessary (e.g. fingerprint reader is not working because the driver is
    missing). The postmarketOS team decides if the port is complete enough for
    the main category based on that list.
* Organize regular meetings with device maintainers.
* Organize regular meetings with vendors (if we have contacts there).
* Long-term commitment for the device.
  * People can step down as needed of course, if possible try to give an
    advance notice.
  * Please don't try to get a device in main if you plan to be away soon.
* Kernel maintenance (Fixing regressions on the kernel side, new kernel
  developments).
* Triage issues found by the community and HW CI regressions.
* Documentation for this device.
* Making sure Hardware CI works (wires are connected, preparing CI).
* Manual testing where necessary.

Rationale:

  • Hardware CI in at least two locations for (in total) at least 3 devices. to have a good uptime (as recommended by CI-tron maintainer Martin Roukala):

    • Two locations means network issues in one location don’t have an impact.

    • Three devices means that one device can be disconnected occasionally for development purposes, and yet if something happens to one of the other two, the CI will still be available.

  • A device maintainer team of at least 5 people, of which the majority are part of the [postmarketOS team](https://postmarketos.org/team).

    • Given that the device maintainer team has a high number of responsibilities, 5 seems like a suitable number.

    • With that being said, the number is arbitrary and we might adjust it later on as we gain more experience.

    • People who are part of the team have shown their commitment for quite some time already (TC requires: “have been contributing to postmarketOS or closely related similar free software projects for the past six months”), so it is more likely that they will stick around for a long time.

  • regular meetings:

    • By having a regular meeting, we give people an incentive to think about topics related to the device port that need to be addressed which may otherwise not happen.

    • If nobody has any points for a specific meeting, it can be cancelled.

The proposer

Oliver Smith (@ollieparanoid), I launched postmarketOS in 2017. Making postmarketOS work reliably is what interests me most in the project right now, and I will be driving this effort forward together with lots of people who have done significant work on this topic throughout the last year (@ncorna, @fizzo, @craftyguy, @pabloyoyoista, @mupuf, @kcxt, @funderscore, @Aelin, @fossdd, @jane400, @Newbyte, @JustSoup321), and everybody else who is interested.

Thanks to all who gave me feedback on these ideas during 39C3, in team meetings, at hackspaces, in the review of this PMCR, at FOSDEM and at the hackathon!

Blocking issues

No blockers for changing the main section of device categorization.