From 35eb5c61cb73c5dbe8e5c2fcba4d5bfde420182f Mon Sep 17 00:00:00 2001 From: Jens Reidel Date: Fri, 31 Oct 2025 10:44:57 +0100 Subject: [PATCH] docs: Replace Antora with Sphinx See https://gitlab.postmarketos.org/postmarketOS/docs.postmarketos.org/-/issues/4 Signed-off-by: Jens Reidel Part-of: --- docs/Makefile | 17 ++ docs/README.md | 18 -- docs/antora.yml | 5 - .../merging-rules.adoc => approval-rules.md} | 29 ++- docs/conf.py | 29 +++ docs/device-categorization.md | 194 +++++++++++++++++ docs/index.md | 19 ++ docs/modules/ROOT/nav.adoc | 2 - .../ROOT/pages/device-categorization.adoc | 199 ------------------ docs/modules/ROOT/pages/index.adoc | 4 - 10 files changed, 273 insertions(+), 243 deletions(-) create mode 100644 docs/Makefile delete mode 100644 docs/README.md delete mode 100644 docs/antora.yml rename docs/{modules/ROOT/pages/merging-rules.adoc => approval-rules.md} (66%) create mode 100644 docs/conf.py create mode 100644 docs/device-categorization.md create mode 100644 docs/index.md delete mode 100644 docs/modules/ROOT/nav.adoc delete mode 100644 docs/modules/ROOT/pages/device-categorization.adoc delete mode 100644 docs/modules/ROOT/pages/index.adoc diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 000000000..bfcb1d823 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,17 @@ +default: venv + . .venv/bin/activate && sphinx-build \ + --fail-on-warning \ + . \ + ../public + +venv: .venv/done +.venv/done: + python3 -m venv .venv + . .venv/bin/activate && pip install "pmos-theme @ git+https://gitlab.postmarketos.org/postmarketOS/docs.postmarketos.org.git/#subdirectory=theme" + touch $@ + +run: + python3 -m http.server -b 127.0.0.1 8081 -d ../public + +.PHONY: default venv run + diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 8eed3ce78..000000000 --- a/docs/README.md +++ /dev/null @@ -1,18 +0,0 @@ -# pmaports docs - -This is part of the postmarketOS handbook. The documentation is built using -[Antora](https://docs.antora.org/antora/latest/) since it allows pulling -information from different repositories, which is a great benefit on a -distributed project like ours. To build the documentation locally install -`nodejs` and `npm` from your favorite package manager, and from the top folder -of the repository run: - -```sh -npm install antora -npx antora --clean antora-test.yml -``` - -After running the commands Antora should print the location of the generated -documentation. - -Alternatively, you can use `pmbootstrap ci build-docs`. diff --git a/docs/antora.yml b/docs/antora.yml deleted file mode 100644 index 965aa9b29..000000000 --- a/docs/antora.yml +++ /dev/null @@ -1,5 +0,0 @@ -name: pmaports -title: Device ports -version: edge -nav: - - modules/ROOT/nav.adoc diff --git a/docs/modules/ROOT/pages/merging-rules.adoc b/docs/approval-rules.md similarity index 66% rename from docs/modules/ROOT/pages/merging-rules.adoc rename to docs/approval-rules.md index bb04c7d5d..d7fb5b5d0 100644 --- a/docs/modules/ROOT/pages/merging-rules.adoc +++ b/docs/approval-rules.md @@ -1,22 +1,21 @@ -= pmaports merging rules = +# pmaports Approval Rules pmaports follows the general -xref:handbook:Technical-Docs:review-merging-guidelines.adoc[merging rules] with -some specific changes +[code review and merge](https://docs.postmarketos.org/policies-and-processes/development/code-review-and-merge.html) +rules, but with the following changes. -== Regular MR approvals == +## Regular MR approvals Most MRs, those not considered critical or trivial require approval by the package maintainer, and by another team member with approval and merge rights. If there is no package maintainer, then 2 any approvals are required. -== Move device from category == +## Move device from category -Moving devices from category is a special operation that requires more work. You -can find further details in the -xref:device-categorization#_review_process[device categorization]. +Moving devices from category is a special operation, see +[device categorization](./device-categorization). -== Enable kernel options across multiple kernels == +## Enable kernel options across multiple kernels Enable kernel options across multiple kernels can be done in one merge request, and requires 2 any approvals from the team, but does not need approvals from @@ -24,17 +23,17 @@ package maintainers. The reason is that would be too much effort to enable kernel options across all kernels. It can be reverted afterwards if there is a good reason. -== Testing requirements == +## Testing requirements Some MRs require testing due to changes affecting multiple devices. In such cases, before merging, in addition to the regular approvals, it is required to: -* *edge*: any person in a MR thread confirms that a MR works. -* *stable*: one person from the team confirms that a MR works. On - device-specific MRs that the team can't test, instead require confirmation of - device maintainer that it works. +* **edge**: any person in a MR thread confirms that a MR works. +* **stable**: one person from the team confirms that a MR works. On + device-specific MRs that the team can't test, instead require confirmation of + device maintainer that it works. -== Backporting == +## Backporting Backporting features from edge to stable is done at request of the MR author or package maintainer. All patches for stable branches must go through edge first diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 000000000..879ce58b0 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,29 @@ +# Configuration file for the Sphinx documentation builder. + +import datetime +import os +import sys + +sys.path.insert(0, os.path.abspath("..")) # Allow modules to be found + +project = "pmaports" +copyright = str(datetime.date.today().year) + ", postmarketOS contributors" +exclude_patterns = ["_build", "_out", "Thumbs.db", ".DS_Store", ".venv", "README.md"] + +extensions = [ + "myst_parser", + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "sphinx.ext.doctest", + "sphinxcontrib.autoprogram", + "sphinxcontrib.jquery", +] + +html_theme = "pmos" +html_theme_options = { + # FIXME: This should be main once we rename the branch + "source_edit_link": "https://gitlab.postmarketos.org/postmarketOS/pmaports/-/blob/master/docs/{filename}", +} + +# Set the explicit title of the HTML output +html_title = "postmarketOS Packaging" diff --git a/docs/device-categorization.md b/docs/device-categorization.md new file mode 100644 index 000000000..74af7a8b4 --- /dev/null +++ b/docs/device-categorization.md @@ -0,0 +1,194 @@ +# Device Categorization + +Devices that are working quite well get lost in the [big matrix of booting +devices](https://wiki.postmarketos.org/wiki/Devices). To improve the situation, +devices postmarketOS runs on have been grouped into the following categories. + +## Categories + +### Main + +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 + +### Community + +Requirements: + +* Maintained by at least one person +* Well documented installation instructions on device wiki page +* Close-to-mainline kernel +* Kernel must pass `pmbootstrap kconfig check --community`, which includes + working firewall + ([#1119](https://gitlab.postmarketos.org/postmarketOS/pmaports/-/issues/1119)) +* Automatic kernel upgrades must work + * When upgrading the kernel, the new kernel must be used on reboot + * Android devices where a new `boot.img` must be flashed after upgrade need + `deviceinfo_flash_kernel_on_update=true`. + * For other devices which directly boot a kernel from a boot partition, or + which use lk2nd, usually nothing needs to be done. +* Maintainer(s) must take part in the workflow for new postmarketOS releases: + * Join the [testing + channel](https://wiki.postmarketos.org/wiki/Matrix_and_IRC) coordinate the + release + * Testing their device and related fixing issues, according to the + [timeline](https://wiki.postmarketos.org/wiki/Creating_a_release_branch#Timeline) + (test yourself/coordinate with the + [Testing Team](https://wiki.postmarketos.org/wiki/Testing_Team); testing + one device per SoC is enough for community devices, but of course more is + better) +* 2021-11 and later: track record of upgrading the kernel, device kernel or SoC + kernel must at least have been upgraded through 3 kernel releases +* Kernel must be upgraded regularly; the kernel version used by the device may not + be older than 6 months. The age of the kernel version is determined by the date + the release was + [tagged](https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/refs/tags) + upstream by Linus Torvalds or the stable kernel maintainers. + For e.g. version 6.12.3, the date would be that of the specific patch release, + not that of the initial 6.12 release + +Regarding device features (calls working, camera, ...), there is not a fixed +feature set (so for users, don't assume that everything works, look at the +device's wiki page for details). + +The purpose of community is to increase visibility of devices that: + +* A lot of work was put into +* Are (and stay) working quite well (i.e. they are useful in some way and are + tested occasionally to find and fix regressions) +* Are still being improved or are considered completed at some point + +### Testing + +Requirements: + +* Must run a close-to-mainline kernel +* Port and dependencies build +* The device boots + +### Downstream + +Requirements: + +* Port and dependencies build +* The device boots + +Notes: + +Device ports using vendor/downstream kernels. Can be moved to _testing_ +once a mainline port appears. Kernels and devices in this category might be +moved to _archived_ if no longer building and either lack a maintainer or the +maintainer is unresponsive for months. + +## Archived + +Ports are moved to this category if: + +* The port has been replaced with a better alternative (e.g. ports using + downstream kernels when a functional mainline port exists). +* The port no longer boots with the current version of postmarketOS, and the + port doesn't have an active maintainer to fix it. + +Archived ports aren't listed in `pmbootstrap init` and binary packages are not +built for them. Still, they can be manually selected and built by entering the +device codename. A warning is displayed with the reason why they have been +archived. + +This category was formerly called *unmaintained* +([!1912](https://gitlab.postmarketos.org/postmarketOS/pmaports/-/merge_requests/1912), +[!5046](https://gitlab.postmarketos.org/postmarketOS/pmaports/-/merge_requests/5046)). + +## Official Images + +Official images are built by [BPO](https://build.postmarketos.org). We +configure the images as follows: + +* Build images for _all_ devices in main and community +* Build images for _some_ devices in testing, maintainers may + [enable building images](https://wiki.postmarketos.org/wiki/Bpo#Image_configuration) if: + * The port runs a mainline kernel. + * The port is actively maintained. + * The maintainer has been active for some time (~6 months). + +We may adjust these rules again, e.g. depending on how many testing devices will +be added over time. Testing images may be removed again, e.g. if they don't +build anymore because of device specific problems. + +## Maintainers + +A device maintainer must own the device and be able to test changes. They must +make sure that the device port stays in good shape. + +## Moving between categories + +### Moving to a higher category + +Moving from testing to community, from community to main or even from testing +straight to main. + +#### Request process + +* Make sure that the device fulfills all requirements for the new category (see + table above). +* Create a new merge request in which you move the files. +* Add new maintainers to the device's APKBUILD, if necessary. + +#### Review process + +* Everyone should be given the chance to look at the entire device port again, + to identify issues/possible improvements. Therefore the MR should not be + merged before a *minimum time of one week* passed. Usually, the MR should be + in good shape when opened, and only minor fixups should need to be done + before merging. If that is the case, then it is one week after the MR was + opened. Otherwise, one week after there were the last significant changes. +* Reviewers should look at all files that were moved and add comments as + necessary. (GitLab currently doesn't allow in-line comments for moved files + ([#213446](https://gitlab.com/gitlab-org/gitlab/-/issues/213446)), so + just add comments below the merge request.) +* Reviewers should verify that the device fulfills all requirements for the new + category (see table above). +* Reviewers should pay special attention to consistency issues, as outlined in + [postmarketos#24](https://gitlab.postmarketos.org/postmarketOS/postmarketos/-/issues/24). +* Consistency issues/possible improvements in the existing features (not + missing features) should be discussed and ideally fixed before merge. + Consistency changes that require lots of work should be documented as issues + an expect to be fixed in the future, but should not unnecessarily delay + merge. +* Before merging, the MR must have at least *four approvals*, 2 of which should + be from Core Contributors. + +#### After merge + +* Change the category of the devices in the wiki +* When moved from testing to community: + [enable building images](https://wiki.postmarketos.org/wiki/Bpo#Image_configuration) + +### Moving to a lower category + +If rules to keep a device in a category are no longer fulfilled, we should +create a merge request to move them to the now appropriate category. + +## See also + +* [postmarketos#25](https://gitlab.postmarketos.org/postmarketOS/postmarketos/-/issues/25) requirements for devices in main +* [postmarketos#24](https://gitlab.postmarketos.org/postmarketOS/postmarketos/-/issues/24) requirements for devices in community +* [postmarketos#16](https://gitlab.postmarketos.org/postmarketOS/postmarketos/-/issues/16) + Increase visibility of actively maintained devices +* [postmarketos#11](https://gitlab.postmarketos.org/postmarketOS/postmarketos/issues/11#get-serious-about-supported-devices) + Get serious about supported devices diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 000000000..f434e0642 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,19 @@ +# Welcome to pmaports' documentation! + +pmaports is the repository that holds the package build definitions in +postmarketOS. + +When porting a new device or doing maintainance work around the distribution, +you will usually be working inside of pmaports. + +This documentation section covers the Dos and Don'ts of packaging software +in pmaports and the processes around device categorization. + +```{eval-rst} +.. toctree:: + :hidden: + + approval-rules + device-categorization +``` + diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc deleted file mode 100644 index dee3ec83e..000000000 --- a/docs/modules/ROOT/nav.adoc +++ /dev/null @@ -1,2 +0,0 @@ -* xref:device-categorization.adoc[Device categorization] -* xref:merging-rules.adoc[Merging rules] diff --git a/docs/modules/ROOT/pages/device-categorization.adoc b/docs/modules/ROOT/pages/device-categorization.adoc deleted file mode 100644 index dd3cc4100..000000000 --- a/docs/modules/ROOT/pages/device-categorization.adoc +++ /dev/null @@ -1,199 +0,0 @@ -= Device categorization - -Devices that are working quite well get lost in the -https://wiki.postmarketos.org/wiki/Devices[big matrix of booting devices]. To -improve the situation, devices postmarketOS runs on have been grouped into the -following categories. - -== Categories == - -[cols="1,1,4"] -|=== -| Category | Actively maintained | Description - -| main -| yes, >= 2 people a| Everything in community, plus required 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 - -Not required (shall change in the future): - -* Camera - -See also: -https://gitlab.postmarketos.org/postmarketOS/postmarketos/-/issues/25[postmarketos#25] - -| community -| yes a| Requirements: - -* Installation instructions must be well documented on device wiki page -* Must run a (close to) mainline kernel -* Kernel must pass `pmbootstrap kconfig check --community`, which includes - working firewall - (https://gitlab.postmarketos.org/postmarketOS/pmaports/-/issues/1119[pmaports#1119]) -* All of them must have automatic kernel upgrade working -** When upgrading the kernel, the new kernel must be used on reboot -** For Android devices this required flashing a new boot image this is - accomplished by setting deviceinfo_flash_kernel_on_update in deviceinfo - https://wiki.postmarketos.org/wiki/Deviceinfo_reference#flash[Deviceinfo - Reference]. -** For other devices which directly boot a kernel from a boot partition, or - which use lk2nd, usually nothing needs to be done. -* Maintainer(s) must take part in the workflow for new postmarketOS releases: -** Join the https://wiki.postmarketos.org/wiki/Matrix_and_IRC[testing] chat to - coordinate the release -** Testing their device and related fixing issues, according to the - https://wiki.postmarketos.org/wiki/Creating_a_release_branch#Timeline[timeline] - (test yourself/coordinate with the - https://wiki.postmarketos.org/wiki/Testing_Team[Testing Team]; testing one - device per SoC is enough for community devices, but of course more is better) -* 2021-11 and later: track record of upgrading the kernel, device kernel or SoC - kernel must at least have been upgraded through 3 kernel releases -* Kernel must be upgraded regularly; the kernel version used by the device may not - be older than 6 months. The age of the kernel version is determined by the date - the release was - https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/refs/tags[tagged] - upstream by Linus Torvalds or the stable kernel maintainers. - For e.g. version 6.12.3, the date would be that of the specific patch release, - not that of the initial 6.12 release - -Regarding device features (calls working, camera, ...), there is not a fixed -feature set (so for users, don't assume that everything works, look at the -device's wiki page for details). - -The purpose of community is to increase visibility of devices that: - -* A lot of work was put into -* Are (and stay) working quite well (i.e. they are useful in some way and are - tested occasionally to find and fix regressions) -* Are still being improved or are considered completed at some point - -See also: See also: -https://gitlab.postmarketos.org/postmarketOS/postmarketos/-/issues/24[postmarketos#24] - -| testing -| no a| Other device ports using a (close-to) mainline kernel, including new -ones. Maintainers can create merge requests to move devices to _community_ if -requirements are met. - -Requirements: - -* Must run a (close to) mainline kernel - -| downstream -| no a| Device ports using vendor/downstream kernels. Can be moved to _testing_ -once a mainline port appears. Kernels and devices in this category might be -moved to _archive_ if no longer building and either lack a maintainer or the -maintainer is unresponsive for months. - -Requirements: - -* Port and dependencies build -* The device boots - -| archived -| no a| Ports are moved to this category if: - -* The port has been replaced with a better alternative (e.g. ports using - downstream kernels when a functional mainline port exists). -* The port no longer boots with the current version of postmarketOS, and the - port doesn't have an active maintainer to fix it. - -Archived ports aren't listed in `pmbootstrap init` and binary packages are not -built for them. Still, they can be manually selected and built by entering the -device codename. A warning is displayed with the reason why they have been -archived. - -This category was formerly called *unmaintained* -(https://gitlab.postmarketos.org/postmarketOS/pmaports/-/merge_requests/1912[pmaports!1912], -https://gitlab.postmarketos.org/postmarketOS/pmaports/-/merge_requests/5046[pmaports!5046]). - -|=== - - -== Official Images == - -Official images are built by -https://wiki.postmarketos.org/wiki/Bpo[bpo]. We configure the images as follows: - -* Build images for _all_ devices in main and community -* Build images for _some_ devices in testing, maintainers may - https://wiki.postmarketos.org/wiki/Bpo#Image_configuration[enable building - images] if: -** The port runs a mainline kernel. -** The port is actively maintained. -** The maintainer has been active for some time (~6 months). - -We may adjust these rules again, e.g. depending on how many testing devices will -be added over time. Testing images may be removed again, e.g. if they don't -build anymore because of device specific problems. - -== Maintainers == - -A device maintainer must own the device and be able to test changes. They must -make sure that the device port stays in good shape. - -== Moving between categories == - -=== Moving to a higher category === - -Moving from testing to community, from community to main or even from testing -straight to main. - -==== Request process ==== - -* Make sure that the device fulfills all requirements for the new category (see - table above). -* Create a new merge request in which you move the files. -* Add new maintainers to the device's APKBUILD, if necessary. - -==== Review process ==== - -* Everyone should be given the chance to look at the entire device port again, - to identify issues/possible improvements. Therefore the MR should not be - merged before a *minimum time of one week* passed. Usually, the MR should be - in good shape when opened, and only minor fixups should need to be done before - merging. If that is the case, then it is one week after the MR was - opened. Otherwise, one week after there were the last significant changes. -* Reviewers should look at all files that were moved and add comments as - necessary. (GitLab currently doesn't allow in-line comments for moved files - (https://gitlab.com/gitlab-org/gitlab/-/issues/213446[gitlab#213446]), so just - add comments below the merge request.) -* Reviewers should verify that the device fulfills all requirements for the new - category (see table above). -* Reviewers should pay special attention to consistency issues, as outlined in - https://gitlab.postmarketos.org/postmarketOS/postmarketos/-/issues/24[postmarketos#24]. -* Consistency issues/possible improvements in the existing features (not missing - features) should be discussed and ideally fixed before merge. Consistency - changes that require lots of work should be documented as issues an expect to - be fixed in the future, but should not unnecessarily delay merge. -* Before merging, the MR must have at least *four approvals*, 2 of which should - be from Core Contributors. - -==== After merge ==== - -* Change the category of the devices in the wiki -* When moved from testing to community: - https://wiki.postmarketos.org/wiki/Bpo#Image_configuration[enable building - images] - -=== Moving to a lower category === - -If rules to keep a device in a category are no longer fulfilled, we should -create a merge request to move them to the now appropriate category. - -== See also == - -* https://gitlab.postmarketos.org/postmarketOS/postmarketos/-/issues/16[postmarketos#16] - Increase visibility of actively maintained devices -* https://gitlab.postmarketos.org/postmarketOS/postmarketos/issues/11#get-serious-about-supported-devices[postmarketos#11] - Get serious about supported devices diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc deleted file mode 100644 index 38f46d1b9..000000000 --- a/docs/modules/ROOT/pages/index.adoc +++ /dev/null @@ -1,4 +0,0 @@ -= Device ports - -This is the documentation related to the `pmaports` repository, and everything -you need to know to understand how to work with device ports in postmarketOS.