From e38532b7f71dccf92c32d5cd8c7fec5f8ca8ae1d Mon Sep 17 00:00:00 2001
From: Achill Gilgenast <achill@achill.org>
Date: Tue, 7 Apr 2026 22:53:25 +0200
Subject: [PATCH] =?UTF-8?q?ci:=20relax=20pkgrel=20changes=20for=20packages?=
 =?UTF-8?q?=20that=20don=E2=80=99t=20have=20remote=20sources?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Motivation is to avoid unnecessary overhead for MR authors & no reason to
actually use pkgrel for meta-packages.

So instead, recommend pkgver-bumps & pkgrel=0 for metapackages, but don't
block MRs when they bumped the "wrong" one. Just make everyone's life easier.

Discussed at <https://docs.postmarketos.org/policies-and-processes/governance/team-meetings/meeting-notes.html> (2026-03-16)

Part-of: <https://gitlab.postmarketos.org/postmarketOS/pmaports/-/merge_requests/8302>
---
 .ci/lib/check_changed_versions.py | 28 ++++++----------------------
 docs/packaging-guidelines.md      | 10 ++++++++++
 2 files changed, 16 insertions(+), 22 deletions(-)

diff --git a/.ci/lib/check_changed_versions.py b/.ci/lib/check_changed_versions.py
index 062573f29..102af1068 100755
--- a/.ci/lib/check_changed_versions.py
+++ b/.ci/lib/check_changed_versions.py
@@ -137,7 +137,7 @@ def check_versions(packages):
         pkgver = head.rpartition('-r')[0]
         if package.startswith('device-') and not pkgver.isdigit():
             print(f" - {package}: invalid pkgver \"{pkgver}\""
-                  "See: https://wiki.postmarketos.org/wiki/Packaging#device_packages_and_other_packages_without_sources")
+                  "See: https://docs.postmarketos.org/pmaports/main/packaging-guidelines.html#package-versioning-pkgver-pkgrel")
             error = True
 
         # Additional checks for device packages
@@ -145,27 +145,11 @@ def check_versions(packages):
             head_parsed = get_package_contents(package, "HEAD", False)
             upstream_parsed = get_package_contents(package, commit, False)
 
-            # checksums did not change
-            if head_parsed["sha512sums"] == upstream_parsed["sha512sums"]:
-                # Check that pkgver did not change
-                if head_parsed["pkgver"] != upstream_parsed["pkgver"]:
-                    print(f" - {package}: pkgver should not change when package source checksums did not change."
-                          "See: https://wiki.postmarketos.org/wiki/Packaging#device_packages_and_other_packages_without_sources")
-                    error = True
-                # We do not check for a bumped pkgrel, because not everything
-                # needs it, e.g: pmb_recommends
-            # checksums changed
-            else:
-                # Check that pkgrel was reset to 0
-                if head_parsed["pkgrel"] != "0":
-                    print(f" - {package}: pkgrel should be 0 when package source checksums change."
-                          "See: https://wiki.postmarketos.org/wiki/Packaging#device_packages_and_other_packages_without_sources")
-                    error = True
-                # Check that pkgver was changed
-                if head_parsed["pkgver"] == upstream_parsed["pkgver"]:
-                    print(f" - {package}: pkgver should change when package source checksums change."
-                          "See: https://wiki.postmarketos.org/wiki/Packaging#device_packages_and_other_packages_without_sources")
-                    error = True
+            # Check that pkgrel was reset to 0 when pkgver was changed
+            if head_parsed["pkgver"] != upstream_parsed["pkgver"] and head_parsed["pkgrel"] != "0":
+                print(f" - {package}: pkgrel should be 0 when pkgver changes."
+                      "See: https://docs.postmarketos.org/pmaports/main/packaging-guidelines.html#package-versioning-pkgver-pkgrel")
+                error = True
 
         # Compare head and upstream versions
         result = pmb.parse.version.compare(head, upstream)
diff --git a/docs/packaging-guidelines.md b/docs/packaging-guidelines.md
index 9e64ea983..77611881a 100644
--- a/docs/packaging-guidelines.md
+++ b/docs/packaging-guidelines.md
@@ -264,3 +264,13 @@ only in some specific circumstances? In those situations we have to:
     versioned provider to disambiguate (e.g:
     `provides="audio-conf=$pkgver-r$pkgrel"`), or to force the forked packages
     to provide a lower version than the other package.
+
+## Meta packages
+
+### Package versioning (pkgver, pkgrel)
+
+Packages without upstream sources are a bit special. These are `device-*`
+packages and other packages like `main/postmarketos-base`, where the source
+files are included in the package directory. For these packages, the `pkgver`
+should always be incremented instead of the `pkgrel` (so that `pkgrel` always
+is `0`).