pkgrel vs pkgver for packaging-only fixes

• When fixing a packaging-only defect in a PKGBUILD (e.g. adding a missing makedepends entry — not a new upstream release), bump pkgrel, not pkgver. Standard Arch convention: pacman already treats a pkgrel increase as an upgrade.
• This is correct even for -git/VCS packages with a pkgver() function that recomputes from the current commit at build time: if the underlying commit hasn’t changed, that function reproduces the same pkgver string, so nothing needs to be forced there either.
• Confirmed with the user 2026-07-07 (asked directly after “if you update makedepends you also have to increase pkgver” was initially read as a literal instruction to bump pkgver itself — turned out to mean pkgrel, which had already been bumped 1->2 for adtpro-git/ c2t-git/etc. while adding a missing makedepends=(git)).
• Applied throughout the 2026-07-07 “build all packages for x86_64” pass for every trivial makedepends fix — see e.g. adtpro-git.md, c2t-git.md, diskm8-git.md, dos33fsprogs-git.md, dsk2nib-git.md, libcurlpp-git.md, llvm-mos-git.md, pcmanfm-gtk3.md, prodos-utilities-git.md.

pkgrel scheme for anything under adapted/ (avoiding a downgrade later)

• Blanket rule, not just “the first local patch”: for any package under arch/adapted/, every local-only pkgrel bump uses X.Y sub-numbering (X.1, X.2, X.3, …), never a plain incremented integer (X+1) — no matter how many local fixes have already happened, and no matter whether pkgver itself has also just changed in the same cycle. adapted/ means the package tracks (or once tracked) some external upstream this project doesn’t control — that external upstream could always resurface at a plain integer pkgrel, so a plain integer bump on the local side is never safe here. pkgver itself must always stay identical to whatever the package’s own version-computation logic (static pkgver=, or a -git package’s pkgver()) produces — never hand-modify pkgver to encode a local revision, only pkgrel.
• Why not a plain incremented pkgrel: this project’s old adapted/p2c fix bumped a plain integer pkgrel (1 -> 2) for a local gcc14-workaround patch on top of upstream’s pkgrel=1. Once upstream fixed the underlying issue in the AUR package itself and this project dropped the local adaptation in favor of building straight from a fresh AUR checkout (now /data/INSTALL/p2c, see memory/hxc-floppy-emulator.md/memory/p2c.md for the install_only_packages pattern this implies), that fresh checkout was still at upstream’s own pkgrel=1 — which vercmp/pacman sees as older than the already-published 2, an apparent downgrade for anyone who already had the locally-patched 2 installed. Using pkgrel=1.1 for the local fix instead would have left plenty of room below any future real upstream pkgrel bump (1.1 < 2), so a subsequent genuine upstream release still correctly sorts as an upgrade over the local patch.
• Also applies right after a -git package’s own pkgver() bumps and makepkg auto-resets pkgrel to a plain 1: got this wrong once already on adapted/pce-git (2026-07-16) — its pkgver() picked up a newer upstream commit mid-session, and makepkg’s own built-in “pkgver changed -> reset pkgrel to 1” logic rewrote the PKGBUILD’s pkgrel back down to plain 1 (not something this project’s pkgver() function does itself — it’s generic makepkg behavior for any VCS package). The very next local fix after that (adding a missing nasm makedepends) still needed pkgrel=1.1, not 1 -> 2 — the new pkgver doesn’t change which category the package is in.
• How to apply: before bumping pkgrel on any adapted/ package, first check whether the current pkgrel already has a .Y suffix or is a “fresh” integer (possibly just reset by a pkgver() change) — either way, the next local-only fix’s pkgrel is <current-integer-part>.<next-Y>, e.g. current 1 or 1.1 both become 1.1 or 1.2 respectively, never 2. maintained/ packages (where this project’s own PKGBUILD is the single source of truth, nothing external to later revert to) are different — plain integer pkgrel bumps are correct there, see the top section of this file. Confirmed with the user 2026-07-16, twice in the same session (pce-git’s checksum fix, then again after its pkgver() bump) — re-read this section fully before every single adapted/ pkgrel bump, don’t rely on remembering the rule from a previous package in the same session.
• Third incident, adapted/fluxengine-git, 2026-07-18: an fmt-12 build fix bumped pkgrel 1 -> plain 2 instead of 1.1, and it got built and published before the mistake was caught. This wasn’t because the package was new and had no memory/fluxengine-git.md yet — that’s not a valid excuse, since this rule already lives in this file (and in cross-session memory) independent of any per-package notes. The rule applies to every adapted/ pkgrel edit, unconditionally, regardless of package history. Corrected to 1.1 and republished the same day.

Content-free rebuilds get X.Y too, even under maintained/

• maintained/pcmciautils, 2026-09-09: pkgrel bumped 9 -> plain 10 purely to force a rebuild across all 4 archs so repo_build.sh’s build-time auto-recording would populate — no actual PKGBUILD content changed (no dep/patch/flag diff). The “maintained/ -> plain integer” rule above only covers genuine content changes; it says nothing about a rebuild with zero content delta. The user’s expectation was 9.1, reserving whole-integer bumps for real packaging changes so the pkgrel history stays meaningful, regardless of maintained/ vs adapted/ category.
• Rule: before any pkgrel bump, plain-integer requires BOTH maintained/ category AND an actual content change. A pure forced-rebuild-for-metrics (or any other content-free rebuild) is always X.Y off the current integer, even under maintained/.
• Caught only after 10 was already built/signed/published across all 4 archs; correcting back to 9.1 at that point would vercmp as a downgrade (vercmp 018-10 018-9.1 = 1), so the user chose to leave the already-live 10 as-is rather than chase it backwards. A mid-flight correction after publish must go forward from whatever integer is already live (e.g. 10.1), never back to what would have been ideal from the prior value.

A purely-additive arch=() edit needs no pkgrel bump at all

• adapted/cyrus-imapd2, 2026-09-10: asked to add a never-before- published pentium4 to arch=(). Reflexively bumped pkgrel 2.5 -> 2.6 (correct X.Y form for adapted/, but the bump itself was the mistake) before the user caught it: “Are you sure we have to bump pkgrel here… Because we are just adding new subarchs.”
• Adding a brand-new arch that has never been published carries no version-skew risk at all — there’s no existing published build for that arch for a bump to protect against. This is the same precedent as pcmciautils’s 2026-09-08 fill-in of never-published i486/i686/pentium4 (also no bump). A bump is only warranted when re-publishing an arch that’s already live (real content change, or a deliberate forced rebuild for consistency/coverage — contrast pcmciautils’s second, 2026-09-10 rebuild above, which did rebuild an already-published x86_64 alongside the new armv7h and legitimately needed the bump).
• How to apply: before touching pkgrel for an arch=() edit, check whether any already-published arch is also being rebuilt under the new pkgrel. Purely additive (new archs only, nothing existing touched) → skip the bump, build the new arch(s) at the PKGBUILD’s current pkgrel alongside the untouched published ones. This question comes before the X.Y-vs-plain-integer question above, not after — X.Y-vs-plain only matters once a bump is already decided to be needed.