COMMITSTYLE: introduce (MR 3908)

COMMITSTYLE.md

@@ -0,0 +1,89 @@
+# Policy for commits in pmaports
+
+This document defines policy for organising and titling commits for
+inclusion in pmaports.
+
+## Definitions
+
+### Device-specific package
+
+A device-specific package is used to apply configuration and
+functionality specifically for device support in postmarketOS.
+This is in contrast to other packages
+(e.g. main/postmarketos-ui-phosh) in postmarketOS that are used
+for configuring the distribution without consideration of the
+target device.
+
+## General policy
+
+We follow Alpine's aports commit style with some minor exceptions
+and additions. Alpine's commit style can be found here:
+https://gitlab.alpinelinux.org/alpine/aports/-/blob/master/COMMITSTYLE.md
+
+## Exceptions
+
+### Changes to packages inside of the device directory
+
+While Alpine has the policy of always prefixing package names with
+the name of the repository they are in, in the case of pmaports
+this can lead to excessively long commit titles due to the nested
+subfolders of the device directory. As such, commits changing
+packages inside of the device directory should omit the directory
+prefix, for example:
+
+	device-pine64-pinephone: description of change
+
+Or:
+
+	soc-qcom-msm8996: description of change
+
+If the commit only makes device-specific changes, the
+commit title can opt to use the following format:
+
+	manufacturer-codename: description of change
+
+### Moving devices between categories
+
+As we do not include directory prefixes in device-related commits,
+Alpine's commit style for moving packages does not apply. Instead,
+we do the following:
+
+	manufacturer-codename: move from category to category
+
+For example:
+
+	samsung-m0: move from testing to community
+
+## Additions
+
+### Forking packages from Alpine
+
+Run `pmbootstrap aportgen --fork-alpine package` and modify it.
+
+#### Template
+
+ - temp/package-name: fork from Alpine
+
+Example: temp/pulseaudio: fork from Alpine
+
+#### Rules
+
+One commit per forked package.
+
+### Adding new devices
+
+Adding a new device package and optionally also a device-specific
+Linux and firmware package.
+
+#### Template
+
+ - manufacturer-codename: new device
+
+Example: htc-m8qlul: new device
+
+#### Rules
+
+If the device has the option of making use of a device-specific
+kernel and/or firmware package, those packages should be included
+in the same commit that adds the device package. One device per
+commit.