From f332f1b30668cb5e0d9d175c63d2675979d50aca Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pablo=20Correa=20G=C3=B3mez?= Date: Wed, 24 Sep 2025 14:34:46 +0200 Subject: [PATCH] docs: add review and merging guidelines specific to pmaports Part-of: --- README.md | 2 +- antora-test.yml | 2 + docs/modules/ROOT/nav.adoc | 1 + .../ROOT/pages/device-categorization.adoc | 4 +- docs/modules/ROOT/pages/merging-rules.adoc | 48 +++++++++++++++++++ 5 files changed, 54 insertions(+), 3 deletions(-) create mode 100644 docs/modules/ROOT/pages/merging-rules.adoc diff --git a/README.md b/README.md index 25251b45d..7cd601e24 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ Helpful resources: * [How to create a package](https://wiki.postmarketos.org/wiki/Create_a_package) * [APKBUILD reference](https://wiki.alpinelinux.org/wiki/APKBUILD_Reference) * [pmaports commit style](./COMMITSTYLE.md) -* [Review and merging guidelines](https://wiki.postmarketos.org/wiki/Rules_for_merging) +* [Review and merging guidelines](./docs/modules/ROOT/pages/merging-rules.adoc) * [Alpine Linux aports](https://gitlab.alpinelinux.org/alpine/aports/) * [Alpine Linux package search](https://pkgs.alpinelinux.org/packages) * [postmarketOS package search](https://pkgs.postmarketos.org/packages) diff --git a/antora-test.yml b/antora-test.yml index c80f11f6d..ccafcfc44 100644 --- a/antora-test.yml +++ b/antora-test.yml @@ -7,6 +7,8 @@ content: - url: . start_path: docs branches: HEAD + - url: https://gitlab.postmarketos.org/postmarketOS/handbook + branches: HEAD ui: bundle: diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index 32514f41c..dee3ec83e 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -1 +1,2 @@ * 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 index 53426043e..8e56c9f2d 100644 --- a/docs/modules/ROOT/pages/device-categorization.adoc +++ b/docs/modules/ROOT/pages/device-categorization.adoc @@ -152,8 +152,6 @@ straight to main. ==== 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. Usually, the MR should be @@ -172,6 +170,8 @@ straight to main. 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 ==== diff --git a/docs/modules/ROOT/pages/merging-rules.adoc b/docs/modules/ROOT/pages/merging-rules.adoc new file mode 100644 index 000000000..58a76389c --- /dev/null +++ b/docs/modules/ROOT/pages/merging-rules.adoc @@ -0,0 +1,48 @@ += pmaports merging rules = + +pmaports follows the general +xref:handbook:Technical-Docs:review-merging-guidelines.adoc[merging rules] with +some specific changes + +== 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 == + +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]. + +== 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 +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 == + +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. + +== Backporting == + +Backporting features from pmaports edge to stable is done in service packs. So +the new feature has some additional testing time in edge, before it potentially +breaks something in stable. + +Critical fixes can be backported immediately, after proper testing to make sure +that there is no breakage. + +All patches for stable branches must go through edge first and get backported +from there. The only exception are patches that fix build failures that only +happen on stable.