docs: document how to create a UI package

Updates and replaces https://wiki.postmarketos.org/wiki/UI_specific_package,
being a bit more specific as to what is expected out of a UI package and
how exactly to create one.

Signed-off-by: Aster Boese <asterboese@mailbox.org>
Part-of: <https://gitlab.postmarketos.org/postmarketOS/pmaports/-/merge_requests/8720>

docs/index.md

@@ -27,4 +27,5 @@ in pmaports and the processes around device categorization.
    kernel-cmdline
    kernel-versions
    packaging-guidelines
+   ui-packages
 ```

docs/ui-packages.md

@@ -0,0 +1,76 @@
+# UI Packages
+
+UIs (otherwise referred to as desktops or 'DE's) are the primary graphical way
+that users interact with their systems. On postmarketOS, these UIs are packaged
+in `postmarketos-ui-*` packages under `main/` in pmaports. The UI packages do not
+include the projects that make up a UI, as those are instead packaged in
+Alpine Linux's aports. The purpose of a UI package in postmarketOS is to
+combine the individual components of a UI, alongside postmarketOS-specific
+configuration, to create a functional out-of-the-box experience for users.
+
+## How to add a new UI
+
+To add a new UI, its components must first be packaged separately and
+upstreamed to Alpine Linux's aports. Once this is complete, a new package
+called `postmarketos-ui-<UI Name>` can be created under the `main/` directory
+in pmaports. If there is more than one UI that uses the same configuration,
+it is also possible to create a `postmarketos-base-ui-<UI Name>` package and
+have the individual UIs depend upon it.
+
+After adding a UI, add it to:
+https://wiki.postmarketos.org/wiki/Category:Interface
+
+## Unique APKBUILD variables and quirks
+
+- **_pmb_groups**
+  - Groups to which the default user should be added to during the
+    installation.
+- **_pmb_recommends**
+  - Packages to install together with the UI, which can be uninstalled by the
+     user.
+- **_pmb_select**
+  - Let `pmbootstrap init` display a prompt for each package in the given list
+    of packages to choose which provider to use for each package.
+- **_pmb_default**
+  - Define the package to display as default during a `pmbootstrap init`
+    `_pmb_select` prompt. Without this, the package with the highest priority
+    will list as default .
+- **pmb:drm**
+  - Adding this to the `options` variable will mark the UI as requiring DRM
+    support to function, hiding it from devices that do not support DRM on
+    `pmbootstrap init`.
+- **pkgdesc**
+  - The same as a normal APKBUILD's `pkgdesc`, but it is also shown during
+    `pmbootstrap init` beside the UI's name.
+
+## Requirements for UI packages
+
+- UIs are not required to support both OpenRC and systemd. While it is
+  recommended to support both to allow user choice, it is up to the UI
+  maintainers whether they support a service manager or not.
+- UIs shall work out-of-the-box on first initialization, meaning that they
+  should not require user intervention to start or require external
+  configuration.
+- UI packages shall attempt to comply with the upstream project's vision
+  for the UI. This is excepted when changes are made to work better with a
+  different device form-factor, to modify basic branding, or to comply with
+  any other requirements.
+- A UI shall be rejected if its inclusion would be a risk to community
+  cohesion through the actions of the UIs upstream community, non-postmarketOS
+  userbase, and/or other outstanding factors that make it obvious that a UI's
+  inclusion would damage the project in some way.
+
+## Recommendations for UI packages
+
+- Only depend upon the minimal amount of packages needed to have a functional
+  desktop as recommended by the upstream. For packages that are not core to
+  the functionality of the desktop, these should be put into `_pmb_recommends`
+  to allow the user to uninstall them if need-be.
+- Create an `$pkgname-extras` subpackage to store the packages (usually apps)
+  that are nice to have, but are not needed for a full experience of the
+  desktop. Apps that could go here are multimedia apps, ebook readers, etc.
+  Remember to put these packages in `_pmb_recommends` in the subpackage to
+  allow the user to uninstall them.
+- If a UI supports the ability to set a wallpaper, it is expected that the
+  default wallpaper of postmarketOS is set by default. This is not a strict
+  rule, as this is sometimes not possible due to technical constraints.