docs: initial documentation for pmaports

Part-of: https://gitlab.postmarketos.org/postmarketOS/pmaports/-/merge_requests/7065

.gitignore

@@ -65,8 +65,9 @@ instance/
 # Scrapy stuff:
 .scrapy
 
-# Sphinx documentation
+# Documentation
 docs/_build/
+build/site
 
 # PyBuilder
 target/

antora-test.yml

@@ -0,0 +1,14 @@
+site:
+  title: Device ports
+  start_page: pmaports::index.adoc
+
+content:
+  sources:
+  - url: .
+    start_path: docs
+    branches: HEAD
+
+ui:
+  bundle:
+    url: ./handbook/ui-bundle
+    snapshot: true

docs/README.md

@@ -0,0 +1,18 @@
+# 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`.

docs/antora.yml

@@ -0,0 +1,5 @@
+name: pmaports
+title: Device ports
+version: edge
+nav:
+  - modules/ROOT/nav.adoc

docs/modules/ROOT/nav.adoc

@@ -0,0 +1 @@
+* xref:device-categorization.adoc[Device categorization]

docs/modules/ROOT/pages/device-categorization.adoc

@@ -0,0 +1,199 @@
+= 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
+
+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
+* Are (and stay) overall in good shape
+
+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)
+** the device is not so obscure that probably nobody will make use of the
+   pre-built images
+
+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 ====
+
+* People with merge access collect approvals as usual, but requires *four
+  approvals* (instead of the usual two).
+* 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.
+** Clarification on the week: 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
+   at least. (Let's not unnecessarily delay merge, that's annoying for
+   everyone.)
+
+==== 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. So far we
+did not come up with extra rules, so we would treat it just like any other merge
+request.
+
+== 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

docs/modules/ROOT/pages/index.adoc

@@ -0,0 +1,4 @@
+= 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.