From 9a8530c89b366586e416f96bffcc2b7ab0f0b80b Mon Sep 17 00:00:00 2001 From: bluebunny Date: Sat, 6 Jun 2026 06:39:34 +0000 Subject: [PATCH] docs: make package versioning more detailed The old wiki page "Packaging" [1] had more information on when to bump packages, but it was omitted when migrating to docs.postmarketos.org. Revive the section and reword the sentences a bit, so that there will be no confusion that the version of a package should always be bumped. [1]: https://wiki.postmarketos.org/index.php?title=Packaging&oldid=68927#When_should_pkgver/pkgrel_get_increased? Part-of: --- docs/packaging-guidelines.md | 26 +++++++++++++++++++------- 1 file changed, 19 insertions(+), 7 deletions(-) diff --git a/docs/packaging-guidelines.md b/docs/packaging-guidelines.md index 4f382c037..54574c12d 100644 --- a/docs/packaging-guidelines.md +++ b/docs/packaging-guidelines.md @@ -29,15 +29,27 @@ Enforcing of this guideline [will wait](https://postmarketos.org/devel/2026/03/24/archiving-unmaintained-devices/) for v26.06 to be released. -## Meta packages +## Package versioning (pkgver, pkgrel) -### Package versioning (pkgver, pkgrel) +Whenever you update a package, the version should also be incremented. A version +consists of `$pkgver-r$pkgrel`, and either `pkgver` or `pkgrel` should be bumped, +even if the changes can be considered trivial. This is to instruct the builder to +rebuild the binary of the package. Likewise, an exception can be made to the rule +if the changes do not affect the built package, such as editing comments, code +style fixes, etc. -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`). +* **pkgver**: The version of the software being packaged. +* **pkgrel**: The release number of the package. Starts at `0`. + +As a general rule, whenever a change is made to upstream sources, `pkgver` should +be increased, and `pkgrel` should be set to `0`. When packaging-related files +(`APKBUILD`, any post-install scripts, patch files to upstream sources, etc.) are +changed, `pkgrel` should be increased. + +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` remains at `0`. ## Provides, priorities, alternatives, and forking packages