pmaports/COMMITSTYLE.md
2023-03-21 08:32:10 +01:00

89 lines
2.3 KiB
Markdown

# 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.