From 2511f29f44142cd6a7350f50b6bc93d743c221ce Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Till=20Kru=CC=88ss?= <till@kruss.io>
Date: Tue, 28 Jul 2026 11:38:19 -0700
Subject: [PATCH 01/13] Fix lintian and rpmlint findings in built packages

Adds a real changelog (closes #4) and clears the packaging metadata
findings reported by lintian 2.122 and rpmlint. Verified by building one
package from every family (deb base/multi/ls, rpm single/multi/ls) at
v0.40.0 and diffing linter output before and after: 8 tags cleared, no
regressions.

- Render deb and rpm changelogs from the cachewerk/relay releases feed.
  The two formats differ and deb entries embed the binary package name,
  so the deb side is a template substituted per package. Bullets are
  re-wrapped to 76 columns to avoid debian-changelog-line-too-long, and
  releases newer than the tag being built are dropped.

- Give packages a real extended description. The synopsis no longer
  starts with an article or ends with a period.

- Ship /usr/share/doc/<pkg>/copyright built from the tarball LICENSE,
  prefixed with a copyright notice. The year comes from the binary mtime
  so the file stays reproducible.

- Drop --provides from the rpm configs. Every one of them set it to the
  package's own name, which rpm already provides implicitly.

Clears: extended-description-is-empty, no-copyright-file,
synopsis-is-a-sentence, description-synopsis-starts-with-article,
syntax-error-in-debian-changelog, useless-provides, no-documentation,
summary-ended-with-dot.

Left alone: the usr/local and opt paths are required by LiteSpeed and
remi; the conffile tags are a policy preference, and dropping
--config-files would overwrite user config on upgrade; invalid-license
cannot be cleared without misstating a proprietary license.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015PwyVggCYKS72z4uS36A2D
---
 .github/workflows/package.yml      |  9 +++
 .gitignore                         |  2 +
 build/changelog.sh                 | 90 ++++++++++++++++++++++++++++++
 build/helpers.sh                   | 32 ++++++++++-
 build/src/rpm/config.ls.el7.sh     |  1 -
 build/src/rpm/config.ls.el8.sh     |  1 -
 build/src/rpm/config.ls.el9.sh     |  1 -
 build/src/rpm/config.multi.el7.sh  |  1 -
 build/src/rpm/config.multi.el8.sh  |  1 -
 build/src/rpm/config.multi.el9.sh  |  1 -
 build/src/rpm/config.single.el7.sh |  1 -
 build/src/rpm/config.single.el8.sh |  1 -
 build/src/rpm/config.single.el9.sh |  1 -
 13 files changed, 132 insertions(+), 10 deletions(-)
 create mode 100755 build/changelog.sh

diff --git a/.github/workflows/package.yml b/.github/workflows/package.yml
index 3b2f839c..94908407 100644
--- a/.github/workflows/package.yml
+++ b/.github/workflows/package.yml
@@ -36,6 +36,15 @@ jobs:
           docker pull ghcr.io/${{ github.repository_owner }}/fpm:latest
           docker tag ghcr.io/${{ github.repository_owner }}/fpm:latest fpm
 
+      # Rendered on the runner rather than inside the container, which has no jq
+      - name: Render changelogs
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh api --paginate 'repos/${{ github.repository_owner }}/relay/releases?per_page=100' \
+            | jq -s 'add' > /tmp/releases.json
+          ./build/changelog.sh /tmp/releases.json '${{ github.event.inputs.tag }}' build
+
       - name: Bundle packages
         run: |
           cd build
diff --git a/.gitignore b/.gitignore
index 075ec491..20f9a475 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,3 +2,5 @@
 /build/src/deb/*-php*
 /build/src/rpm/*-php*
 key-private.asc
+/build/changelog.deb.tpl
+/build/changelog.rpm
diff --git a/build/changelog.sh b/build/changelog.sh
new file mode 100755
index 00000000..d3a6e9dd
--- /dev/null
+++ b/build/changelog.sh
@@ -0,0 +1,90 @@
+#!/bin/bash
+
+# Renders Debian and RPM changelogs from the cachewerk/relay GitHub releases feed.
+#
+#   changelog.sh <releases.json> <version> <out_dir>
+#
+# Writes:
+#   $out_dir/changelog.deb.tpl   Debian format, with @PKG@ standing in for the binary
+#                                package name (substituted per package by fpm_build)
+#   $out_dir/changelog.rpm       RPM %changelog format
+#
+# Releases newer than $version are dropped so a rebuild of an older tag does not
+# claim changes it does not contain.
+
+set -e
+
+releases=$1
+version=${2#v}
+out=$3
+
+maintainer="Relay Team <hello@cachewerk.com>"
+
+# Release notes are written for GitHub and routinely exceed 80 columns, which
+# lintian flags as debian-changelog-line-too-long. Re-wrap the bullet lines.
+wrap_bullets()
+{
+  awk -v prefix="$1" -v cont="$2" -v max=76 '
+    index($0, prefix) != 1 { print; next }
+    {
+      text = substr($0, length(prefix) + 1)
+      n = split(text, w, " ")
+      line = prefix w[1]
+      for (i = 2; i <= n; i++) {
+        if (length(line) + 1 + length(w[i]) > max) { print line; line = cont w[i] }
+        else line = line " " w[i]
+      }
+      print line
+    }'
+}
+
+# The topmost entry has to match the version being packaged, so refuse to run
+# rather than emit a changelog that claims the wrong release.
+if ! jq -e --arg v "$version" 'any(.[]; (.draft | not) and (.tag_name | ltrimstr("v")) == $v)' \
+     "$releases" > /dev/null; then
+  echo "No published release found for $version" >&2
+  exit 1
+fi
+
+# Newest first, drop drafts, drop anything above the version being built.
+filtered=$(jq --arg v "$version" '
+  map(select(.draft | not))
+  | sort_by(.published_at)
+  | reverse
+  | map(. + {ver: (.tag_name | ltrimstr("v"))})
+  | (map(.ver) | index($v)) as $i
+  | .[$i:]
+' "$releases")
+
+# Bullet lines out of the Keep-a-Changelog markdown body, "### Added" headings dropped.
+bullets='
+  (.body // "")
+  | gsub("\r"; "")
+  | split("\n")
+  | map(select(test("^\\s*[-*]\\s+\\S")))
+  | map(sub("^\\s*[-*]\\s+"; ""))
+  | map(gsub("\\s+$"; ""))
+'
+
+echo "$filtered" | jq -r --arg m "$maintainer" "
+  .[]
+  | ($bullets) as \$b
+  | (if (\$b | length) == 0 then [\"Relay \" + .ver] else \$b end) as \$b
+  | \"@PKG@ (\" + .ver + \") unstable; urgency=medium\n\n\"
+    + (\$b | map(\"  * \" + .) | join(\"\n\"))
+    + \"\n\n -- \" + \$m + \"  \"
+    + (.published_at | fromdateiso8601 | strftime(\"%a, %d %b %Y %H:%M:%S +0000\"))
+    + \"\n\"
+" | wrap_bullets "  * " "    " > "$out/changelog.deb.tpl"
+
+echo "$filtered" | jq -r --arg m "$maintainer" "
+  .[]
+  | ($bullets) as \$b
+  | (if (\$b | length) == 0 then [\"Relay \" + .ver] else \$b end) as \$b
+  | \"* \" + (.published_at | fromdateiso8601 | strftime(\"%a %b %d %Y\"))
+    + \" \" + \$m + \" - \" + .ver + \"-1\n\"
+    + (\$b | map(\"- \" + .) | join(\"\n\"))
+    + \"\n\"
+" | wrap_bullets "- " "  " > "$out/changelog.rpm"
+
+echo "Wrote $(grep -c '^@PKG@' "$out/changelog.deb.tpl") deb entries, $(grep -c '^\* ' "$out/changelog.rpm") rpm entries"
diff --git a/build/helpers.sh b/build/helpers.sh
index 07b530cd..2da726b5 100755
--- a/build/helpers.sh
+++ b/build/helpers.sh
@@ -1,4 +1,13 @@
 
+# NOTE: must NOT be named pkg_*, main() runs `unset ${!pkg_@}` before every build
+read -r -d '' relay_description <<'DESCRIPTION' || true
+Next-generation caching layer for PHP
+Relay is a fast, persistent, in-memory cache for PHP that serves as a drop-in
+replacement for PhpRedis. It keeps a partial replica of the Redis or Valkey
+data set inside the PHP process, avoiding network round trips and decoding
+costs for cached keys.
+DESCRIPTION
+
 main()
 {
   rm -rf /tmp/relay*
@@ -57,6 +66,19 @@ fpm_build()
     cp $src_path/relay.ini $dest_path/$config_file
   done
 
+  # Debian policy requires /usr/share/doc/<pkg>/copyright; rpm wants documentation.
+  # The year comes from the binary's mtime so the file stays reproducible.
+  mkdir -p $dest_path/usr/share/doc/$pkg_name
+  {
+    echo "Copyright (C) 2021-$(date -u -d @$(stat -c %Y $src_path/relay.so) +%Y) CacheWerk, Inc."
+    echo "All rights reserved."
+    echo
+    echo "Relay is proprietary software, licensed under the End-User License"
+    echo "Agreement reproduced below."
+    echo
+    cat $src_path/LICENSE
+  } > $dest_path/usr/share/doc/$pkg_name/copyright
+
   pkg_version=${version#v}
   pkg_filename="${pkg_name}-${pkg_version}-php${php_version}-${pkg_identifier}-${pkg_arch}.${type}"
 
@@ -66,7 +88,7 @@ fpm_build()
 
     "--vendor 'CacheWerk, Inc.'"
     "--maintainer 'Relay Team <hello@cachewerk.com>'"
-    "--description 'The next-generation caching layer for PHP.'"
+    "--description '$relay_description'"
     "--url 'https://relay.so'"
     "--license 'Proprietary'"
     "--category 'php'"
@@ -84,6 +106,14 @@ fpm_build()
     "--deb-no-default-config-files"
   )
 
+  # changelogs: deb entries embed the binary package name, rpm entries do not
+  if [[ "$type" == "deb" ]]; then
+    sed "s/@PKG@/$pkg_name/g" /root/build/changelog.deb.tpl > /tmp/changelog-$pkg_name.deb
+    args+=("--deb-changelog /tmp/changelog-$pkg_name.deb")
+  else
+    args+=("--rpm-changelog /root/build/changelog.rpm")
+  fi
+
   if [ ! -z "$pkg_provides" ]; then
     args+=("--provides '$pkg_provides'")
   fi
diff --git a/build/src/rpm/config.ls.el7.sh b/build/src/rpm/config.ls.el7.sh
index 36895bb7..1ec39a47 100644
--- a/build/src/rpm/config.ls.el7.sh
+++ b/build/src/rpm/config.ls.el7.sh
@@ -1,7 +1,6 @@
 #!/bin/bash
 
 pkg_name="lsphp$php_version_short-relay"
-pkg_provides="lsphp$php_version_short-relay"
 pkg_binary="relay-pkg.so"
 pkg_identifier="el7"
 
diff --git a/build/src/rpm/config.ls.el8.sh b/build/src/rpm/config.ls.el8.sh
index 2a74cecd..40372728 100644
--- a/build/src/rpm/config.ls.el8.sh
+++ b/build/src/rpm/config.ls.el8.sh
@@ -1,7 +1,6 @@
 #!/bin/bash
 
 pkg_name="lsphp$php_version_short-relay"
-pkg_provides="lsphp$php_version_short-relay"
 pkg_binary="relay-pkg.so"
 pkg_identifier="el8"
 
diff --git a/build/src/rpm/config.ls.el9.sh b/build/src/rpm/config.ls.el9.sh
index f77cc12d..d7a48898 100644
--- a/build/src/rpm/config.ls.el9.sh
+++ b/build/src/rpm/config.ls.el9.sh
@@ -1,7 +1,6 @@
 #!/bin/bash
 
 pkg_name="lsphp$php_version_short-relay"
-pkg_provides="lsphp$php_version_short-relay"
 pkg_binary="relay-pkg.so"
 pkg_identifier="el9"
 
diff --git a/build/src/rpm/config.multi.el7.sh b/build/src/rpm/config.multi.el7.sh
index b8f199a8..1a4e2269 100644
--- a/build/src/rpm/config.multi.el7.sh
+++ b/build/src/rpm/config.multi.el7.sh
@@ -1,7 +1,6 @@
 #!/bin/bash
 
 pkg_name="php$php_version_short-php-relay"
-pkg_provides="php$php_version_short-php-relay"
 pkg_binary="relay-pkg.so"
 pkg_identifier="el7"
 
diff --git a/build/src/rpm/config.multi.el8.sh b/build/src/rpm/config.multi.el8.sh
index abe0f0cb..9655735f 100644
--- a/build/src/rpm/config.multi.el8.sh
+++ b/build/src/rpm/config.multi.el8.sh
@@ -1,7 +1,6 @@
 #!/bin/bash
 
 pkg_name="php$php_version_short-php-relay"
-pkg_provides="php$php_version_short-php-relay"
 pkg_binary="relay-pkg.so"
 pkg_identifier="el8"
 
diff --git a/build/src/rpm/config.multi.el9.sh b/build/src/rpm/config.multi.el9.sh
index 1b602302..7b80f679 100644
--- a/build/src/rpm/config.multi.el9.sh
+++ b/build/src/rpm/config.multi.el9.sh
@@ -1,7 +1,6 @@
 #!/bin/bash
 
 pkg_name="php$php_version_short-php-relay"
-pkg_provides="php$php_version_short-php-relay"
 pkg_binary="relay-pkg.so"
 pkg_identifier="el9"
 
diff --git a/build/src/rpm/config.single.el7.sh b/build/src/rpm/config.single.el7.sh
index 403b16ba..d879f5a4 100644
--- a/build/src/rpm/config.single.el7.sh
+++ b/build/src/rpm/config.single.el7.sh
@@ -1,7 +1,6 @@
 #!/bin/bash
 
 pkg_name="php-relay"
-pkg_provides="php-relay"
 pkg_binary="relay-pkg.so"
 pkg_identifier="el7"
 
diff --git a/build/src/rpm/config.single.el8.sh b/build/src/rpm/config.single.el8.sh
index aec7826f..f1efe042 100644
--- a/build/src/rpm/config.single.el8.sh
+++ b/build/src/rpm/config.single.el8.sh
@@ -1,7 +1,6 @@
 #!/bin/bash
 
 pkg_name="php-relay"
-pkg_provides="php-relay"
 pkg_binary="relay-pkg.so"
 pkg_identifier="el8"
 
diff --git a/build/src/rpm/config.single.el9.sh b/build/src/rpm/config.single.el9.sh
index a7c58a26..f6cc94ac 100644
--- a/build/src/rpm/config.single.el9.sh
+++ b/build/src/rpm/config.single.el9.sh
@@ -1,7 +1,6 @@
 #!/bin/bash
 
 pkg_name="php-relay"
-pkg_provides="php-relay"
 pkg_binary="relay-pkg.so"
 pkg_identifier="el9"
 

From c7e6de390fe404f1748ec4e3e10fc50eb585cd44 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Till=20Kru=CC=88ss?= <till@kruss.io>
Date: Tue, 28 Jul 2026 12:36:38 -0700
Subject: [PATCH 02/13] Clear the remaining fixable lint findings

- Omit `Vendor` from debs. It is a real rpm tag but not a valid Debian
  control field. fpm guards the deb line with `!vendor.empty?`, so an
  explicit empty value drops it; rpm keeps the vendor. The same trick does
  not work on `License` -- that line is emitted unconditionally, so an empty
  value would add `empty-field` on top of the existing `unknown-field`.

- Describe php-relay as a metapackage. It ships no files of its own, and the
  word "metapackage" is what tells lintian to skip its empty-package and
  arch-dependent-files checks. Avoids needing `Architecture: all`, which
  would break the arch suffix rename in deb-repo.sh.

- Stamp packages with the release date instead of the binary mtime. fpm
  stamps the gzipped changelog with the source date epoch, and lintian flags
  the package when that is newer than the newest changelog entry. On v0.40.0
  the binary mtime was 206s later than the release, so every deb tripped it.

Clears: unknown-field (Vendor), empty-binary-package,
package-contains-no-arch-dependent-files, package-contains-timestamped-gzip.

Cumulative with the previous commit: 12 tags, no regressions, verified by
building one package from every family and diffing linter output.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015PwyVggCYKS72z4uS36A2D
---
 .gitignore                   |  1 +
 build/changelog.sh           |  5 +++++
 build/helpers.sh             | 17 +++++++++++++----
 build/src/deb/config.base.sh |  5 +++++
 4 files changed, 24 insertions(+), 4 deletions(-)

diff --git a/.gitignore b/.gitignore
index 20f9a475..72f06f4c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,3 +4,4 @@
 key-private.asc
 /build/changelog.deb.tpl
 /build/changelog.rpm
+/build/changelog.epoch
diff --git a/build/changelog.sh b/build/changelog.sh
index d3a6e9dd..ac39e338 100755
--- a/build/changelog.sh
+++ b/build/changelog.sh
@@ -87,4 +87,9 @@ echo "$filtered" | jq -r --arg m "$maintainer" "
     + \"\n\"
 " | wrap_bullets "- " "  " > "$out/changelog.rpm"
 
+# Timestamp of the release being packaged. fpm stamps the gzipped changelog with
+# the source date epoch, and lintian flags the package when that is newer than
+# the newest changelog entry, so the two have to come from the same place.
+echo "$filtered" | jq -r '.[0].published_at | fromdateiso8601' > "$out/changelog.epoch"
+
 echo "Wrote $(grep -c '^@PKG@' "$out/changelog.deb.tpl") deb entries, $(grep -c '^\* ' "$out/changelog.rpm") rpm entries"
diff --git a/build/helpers.sh b/build/helpers.sh
index 2da726b5..50fde52c 100755
--- a/build/helpers.sh
+++ b/build/helpers.sh
@@ -67,10 +67,10 @@ fpm_build()
   done
 
   # Debian policy requires /usr/share/doc/<pkg>/copyright; rpm wants documentation.
-  # The year comes from the binary's mtime so the file stays reproducible.
+  # The year comes from the release date so the file stays reproducible.
   mkdir -p $dest_path/usr/share/doc/$pkg_name
   {
-    echo "Copyright (C) 2021-$(date -u -d @$(stat -c %Y $src_path/relay.so) +%Y) CacheWerk, Inc."
+    echo "Copyright (C) 2021-$(date -u -d @$(cat /root/build/changelog.epoch) +%Y) CacheWerk, Inc."
     echo "All rights reserved."
     echo
     echo "Relay is proprietary software, licensed under the End-User License"
@@ -86,7 +86,6 @@ fpm_build()
     "--input-type dir"
     "--output-type $type"
 
-    "--vendor 'CacheWerk, Inc.'"
     "--maintainer 'Relay Team <hello@cachewerk.com>'"
     "--description '$relay_description'"
     "--url 'https://relay.so'"
@@ -97,7 +96,7 @@ fpm_build()
     "--architecture $pkg_arch"
 
     "--package dist/$pkg_filename"
-    "--source-date-epoch-default $(stat -c %Y $src_path/relay.so)"
+    "--source-date-epoch-default $(cat /root/build/changelog.epoch)"
 
     "--template-value binary_paths='$pkg_binary_dest'"
     "--template-value php_version='$php_version'"
@@ -106,6 +105,16 @@ fpm_build()
     "--deb-no-default-config-files"
   )
 
+  # `Vendor` is a real rpm tag but not a valid Debian control field. fpm guards
+  # the deb line with `!vendor.empty?`, so an explicit empty value omits it.
+  # Don't try the same on --license: that line is emitted unconditionally, so an
+  # empty value adds `empty-field` on top of the existing `unknown-field`.
+  if [[ "$type" == "rpm" ]]; then
+    args+=("--vendor 'CacheWerk, Inc.'")
+  else
+    args+=("--vendor ''")
+  fi
+
   # changelogs: deb entries embed the binary package name, rpm entries do not
   if [[ "$type" == "deb" ]]; then
     sed "s/@PKG@/$pkg_name/g" /root/build/changelog.deb.tpl > /tmp/changelog-$pkg_name.deb
diff --git a/build/src/deb/config.base.sh b/build/src/deb/config.base.sh
index ee5eb50e..5ba3fedd 100644
--- a/build/src/deb/config.base.sh
+++ b/build/src/deb/config.base.sh
@@ -24,4 +24,9 @@ pkg_depends=(
 fpm_args=(
   "--deb-pre-depends 'php-common'"
   "--after-install /root/build/src/deb/after-install.sh"
+
+  # This package ships no files of its own. The word "metapackage" is what tells
+  # lintian to skip its empty-package and arch-dependent-files checks, so keep
+  # it. The $'...' quoting is required: fpm does not expand \n in --description.
+  "--description $'Relay metapackage for PHP $php_version\nThis dependency metapackage pulls in the Relay extension for PHP\n$php_version along with its companion extensions.'"
 )

From 29c0396e88badb177ac62fd3f4b2f4bb4c8fa61d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Till=20Kru=CC=88ss?= <till@kruss.io>
Date: Tue, 28 Jul 2026 12:54:02 -0700
Subject: [PATCH 03/13] Add deb removal script and bundled library licenses

Closes #1, closes #3. Also closes #2, which tracked the same removal and
upgrade correctness as #1.

after-remove-multi.sh is the counterpart to after-install-multi.sh, which
is the only script that enables the module. Without it, removing the
package left relay enabled pointing at a deleted relay.so, so PHP emitted
a startup warning on every invocation:

  PHP Warning:  PHP Startup: Unable to load dynamic library 'relay.so'

It follows what Debian's own PHP extension packages do in postrm: dismod
on remove, sweep leftover symlinks on purge, and guard on `$1` so an
upgrade does not disable the extension. Every call tolerates failure --
by the time postrm runs the PHP tooling may already be gone, and nothing
here may block removal.

relay-pkg.so statically links hiredis and ck, so their notices now ship
in the copyright file. Verified against the binary rather than assumed:
redisConnect and ck_rhs_init are in the symbol table, while lz4 and zstd
are dlopen'd at runtime and jemalloc is absent entirely, so neither is
bundled and neither needs a notice. The plain relay.so used on noble,
plucky and trixie links hiredis and ck dynamically and is covered by the
distribution's own packages, so the notices are conditional on the
binary variant.

ck's license also carries an Apache-2.0 notice for src/ck_hp.c, which
needs the shipped copy referenced rather than the notice standing alone.

Verified on Debian trixie with real PHP 8.4: install enables cli and fpm
and the extension loads, upgrade leaves it enabled, remove disables it
cleanly, purge leaves nothing behind, and PHP still starts without
warnings afterwards.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015PwyVggCYKS72z4uS36A2D
---
 build/helpers.sh                    | 20 +++++++++++
 build/licenses/ck.txt               | 54 +++++++++++++++++++++++++++++
 build/licenses/hiredis.txt          | 29 ++++++++++++++++
 build/src/deb/after-remove-multi.sh | 32 +++++++++++++++++
 build/src/deb/config.multi.sh       |  1 +
 5 files changed, 136 insertions(+)
 create mode 100644 build/licenses/ck.txt
 create mode 100644 build/licenses/hiredis.txt
 create mode 100644 build/src/deb/after-remove-multi.sh

diff --git a/build/helpers.sh b/build/helpers.sh
index 50fde52c..e14309ab 100755
--- a/build/helpers.sh
+++ b/build/helpers.sh
@@ -77,6 +77,26 @@ fpm_build()
     echo "Agreement reproduced below."
     echo
     cat $src_path/LICENSE
+
+    # relay-pkg.so statically links hiredis and ck, so their notices have to
+    # ship with it. The plain relay.so links both dynamically and is covered by
+    # the distribution's own packages. lz4 and zstd are dlopen'd either way.
+    if [[ "$pkg_binary" == *-pkg* ]]; then
+      for bundled in hiredis ck; do
+        echo
+        echo "------------------------------------------------------------------------------"
+        echo
+        echo "This build statically links $bundled, distributed under the following terms:"
+        echo
+        cat /root/build/licenses/$bundled.txt
+      done
+
+      # ck carries an Apache-2.0 notice for src/ck_hp.c. Debian policy wants the
+      # shipped copy referenced rather than the notice standing alone.
+      echo
+      echo "On Debian systems the complete text of the Apache License, Version 2.0"
+      echo "can be found in /usr/share/common-licenses/Apache-2.0."
+    fi
   } > $dest_path/usr/share/doc/$pkg_name/copyright
 
   pkg_version=${version#v}
diff --git a/build/licenses/ck.txt b/build/licenses/ck.txt
new file mode 100644
index 00000000..73b0eeb1
--- /dev/null
+++ b/build/licenses/ck.txt
@@ -0,0 +1,54 @@
+Copyright 2010-2014 Samy Al Bahra.
+Copyright 2011-2013 AppNexus, Inc.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGE.
+
+Hazard Pointers (src/ck_hp.c) also includes this license:
+
+(c) Copyright 2008, IBM Corporation.
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+ck_pr_rtm leverages work from Andi Kleen:
+Copyright (c) 2012,2013 Intel Corporation
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that: (1) source code distributions
+retain the above copyright notice and this paragraph in its entirety, (2)
+distributions including binary code include the above copyright notice and
+this paragraph in its entirety in the documentation or other materials
+provided with the distribution
+
+THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
+WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+
diff --git a/build/licenses/hiredis.txt b/build/licenses/hiredis.txt
new file mode 100644
index 00000000..a5fc9739
--- /dev/null
+++ b/build/licenses/hiredis.txt
@@ -0,0 +1,29 @@
+Copyright (c) 2009-2011, Salvatore Sanfilippo <antirez at gmail dot com>
+Copyright (c) 2010-2011, Pieter Noordhuis <pcnoordhuis at gmail dot com>
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice,
+  this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of Redis nor the names of its contributors may be used
+  to endorse or promote products derived from this software without specific
+  prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
diff --git a/build/src/deb/after-remove-multi.sh b/build/src/deb/after-remove-multi.sh
new file mode 100644
index 00000000..deeea9b6
--- /dev/null
+++ b/build/src/deb/after-remove-multi.sh
@@ -0,0 +1,32 @@
+#!/bin/bash
+
+set -e
+
+# Counterpart to after-install-multi.sh, which enables the module. Without this,
+# removing the package leaves relay enabled and PHP loads a relay.so that is no
+# longer there. Mirrors what Debian's own PHP extension packages do in postrm.
+#
+# Nothing here may abort the removal, so every call tolerates failure: by the
+# time this runs the PHP tooling may already be gone.
+
+if [ "$1" = "remove" ]; then
+  if [ -e /usr/lib/php/php-maintscript-helper ]; then
+    . /usr/lib/php/php-maintscript-helper
+    php_invoke dismod "<%= php_version %>" ALL relay || true
+  elif command -v phpdismod > /dev/null; then
+    phpdismod -v "<%= php_version %>" relay || true
+  fi
+fi
+
+# dpkg removes the conffile itself, but the symlinks phpenmod created are not
+# owned by the package. Sweep any that still point at our ini, which is what is
+# left behind when the helper above was already unavailable.
+if [ "$1" = "purge" ]; then
+  find "/etc/php/<%= php_version %>" -type l 2>/dev/null | while read -r symlink; do
+    if [ "$(basename "$(readlink -m "${symlink}")")" = "relay.ini" ]; then
+      rm -f "${symlink}"
+    fi
+  done
+fi
+
+exit 0
diff --git a/build/src/deb/config.multi.sh b/build/src/deb/config.multi.sh
index d2812456..d28cbda1 100644
--- a/build/src/deb/config.multi.sh
+++ b/build/src/deb/config.multi.sh
@@ -38,4 +38,5 @@ fpm_args=(
   "--deb-pre-depends 'php-common'"
   "--deb-field 'Source: php-relay'"
   "--after-install /root/build/src/deb/after-install-multi.sh"
+  "--after-remove /root/build/src/deb/after-remove-multi.sh"
 )

From e40441a9974979a7cd8cab27971e5d20d2b2f27c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Till=20Kru=CC=88ss?= <till@kruss.io>
Date: Tue, 28 Jul 2026 13:05:36 -0700
Subject: [PATCH 04/13] Declare the LiteSpeed layout with lintian overrides

The lsphp packages install into /usr/local/lsws, because that is where
LiteSpeed keeps its bundled PHP. That is not something this repo can
change, and the ini has to stay a conffile despite living outside /etc or
a user's settings would be overwritten on every upgrade. Both are correct
behaviour, so declare them instead of leaving them reported as defects.

Clears 5 tags across the deb matrix: dir-in-usr-local, file-in-usr-local,
file-in-unusual-dir, file-in-usr-marked-as-conffile and
non-etc-file-marked-as-conffile. Verified every override matches, so
lintian reports no unused-override.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015PwyVggCYKS72z4uS36A2D
---
 build/helpers.sh           |  9 +++++++++
 build/src/deb/config.ls.sh | 12 ++++++++++++
 2 files changed, 21 insertions(+)

diff --git a/build/helpers.sh b/build/helpers.sh
index e14309ab..e6c7beff 100755
--- a/build/helpers.sh
+++ b/build/helpers.sh
@@ -99,6 +99,15 @@ fpm_build()
     fi
   } > $dest_path/usr/share/doc/$pkg_name/copyright
 
+  # Tags that are correct behaviour here and cannot be resolved without breaking
+  # the package, declared so they stop being reported as defects.
+  if [[ "$type" == "deb" && ${#pkg_lintian_overrides[@]} -gt 0 ]]; then
+    mkdir -p $dest_path/usr/share/lintian/overrides
+    for tag in "${pkg_lintian_overrides[@]}"; do
+      echo "$pkg_name binary: $tag"
+    done > $dest_path/usr/share/lintian/overrides/$pkg_name
+  fi
+
   pkg_version=${version#v}
   pkg_filename="${pkg_name}-${pkg_version}-php${php_version}-${pkg_identifier}-${pkg_arch}.${type}"
 
diff --git a/build/src/deb/config.ls.sh b/build/src/deb/config.ls.sh
index c9dd0b5b..53becdcb 100644
--- a/build/src/deb/config.ls.sh
+++ b/build/src/deb/config.ls.sh
@@ -32,6 +32,18 @@ pkg_depends=(
   "libck0 >= 0.7.0"
 )
 
+# LiteSpeed keeps its bundled PHP under /usr/local, so these packages cannot
+# follow the FHS the way the regular ones do. The ini has to stay a conffile
+# despite living outside /etc, or a user's settings would be overwritten on
+# every upgrade.
+pkg_lintian_overrides=(
+  "dir-in-usr-local"
+  "file-in-usr-local"
+  "file-in-unusual-dir"
+  "file-in-usr-marked-as-conffile"
+  "non-etc-file-marked-as-conffile"
+)
+
 fpm_args=(
   "--after-install /root/build/src/deb/after-install.sh"
 )

From 21c55e1490accabd2583105f9b1edf7353b96421 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Till=20Kru=CC=88ss?= <till@kruss.io>
Date: Tue, 28 Jul 2026 13:10:43 -0700
Subject: [PATCH 05/13] Demote lz4 and zstd to weak dependencies

Since v0.40.0 Relay dlopens liblz4 and libzstd at startup rather than
linking them -- neither appears in the NEEDED entries of relay.so or
relay-pkg.so -- but the packages still required them outright, so every
install pulled in libraries Relay only optionally uses.

They are now Recommends, which apt installs by default, so in practice
nobody loses compression; --no-install-recommends users and container
builds can opt out, which is the point.

el7 keeps them as hard requires. Weak dependencies arrived in rpm 4.12
and el7 ships 4.11.3, so a Recommends there is read and then ignored,
which would silently stop installing them for exactly the users least
likely to notice. Verified on centos:7 that such a package still parses
and installs; it simply drops the tag. The cost is that
explicit-lib-dependency stays on the el7 rpms.

Clears explicit-lib-dependency on el8 and el9.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015PwyVggCYKS72z4uS36A2D
---
 build/src/deb/config.ls.sh         | 6 ++++--
 build/src/deb/config.multi.sh      | 6 ++++--
 build/src/rpm/config.ls.el8.sh     | 7 +++++--
 build/src/rpm/config.ls.el9.sh     | 7 +++++--
 build/src/rpm/config.multi.el8.sh  | 7 +++++--
 build/src/rpm/config.multi.el9.sh  | 7 +++++--
 build/src/rpm/config.single.el8.sh | 7 +++++--
 build/src/rpm/config.single.el9.sh | 7 +++++--
 8 files changed, 38 insertions(+), 16 deletions(-)

diff --git a/build/src/deb/config.ls.sh b/build/src/deb/config.ls.sh
index 53becdcb..4d8f223e 100644
--- a/build/src/deb/config.ls.sh
+++ b/build/src/deb/config.ls.sh
@@ -20,8 +20,6 @@ pkg_config_dest=(
 
 pkg_depends=(
     "libc6 >= 2.17"
-    "liblz4-1 >= 0.0~r130"
-    "libzstd1 >= 1.3.2"
     "lsphp$php_version_short-common"
     "lsphp$php_version_short-igbinary"
     "lsphp$php_version_short-msgpack"
@@ -45,5 +43,9 @@ pkg_lintian_overrides=(
 )
 
 fpm_args=(
+  # Relay dlopens these at startup rather than linking them, so they are
+  # wanted but not required.
+  "--deb-recommends 'liblz4-1 (>= 0.0~r130)'"
+  "--deb-recommends 'libzstd1 (>= 1.3.2)'"
   "--after-install /root/build/src/deb/after-install.sh"
 )
diff --git a/build/src/deb/config.multi.sh b/build/src/deb/config.multi.sh
index d28cbda1..27be25b8 100644
--- a/build/src/deb/config.multi.sh
+++ b/build/src/deb/config.multi.sh
@@ -21,8 +21,6 @@ pkg_config_dest=(
 
 pkg_depends=(
     "libc6 >= 2.17"
-    "liblz4-1 >= 0.0~r130"
-    "libzstd1 >= 1.3.2"
     "php$php_version-common"
     "php$php_version-igbinary"
     "php$php_version-msgpack"
@@ -34,6 +32,10 @@ pkg_depends=(
 )
 
 fpm_args=(
+  # Relay dlopens these at startup rather than linking them, so they are
+  # wanted but not required.
+  "--deb-recommends 'liblz4-1 (>= 0.0~r130)'"
+  "--deb-recommends 'libzstd1 (>= 1.3.2)'"
   "--replaces 'php-relay << ${version#v}'"
   "--deb-pre-depends 'php-common'"
   "--deb-field 'Source: php-relay'"
diff --git a/build/src/rpm/config.ls.el8.sh b/build/src/rpm/config.ls.el8.sh
index 40372728..998d2440 100644
--- a/build/src/rpm/config.ls.el8.sh
+++ b/build/src/rpm/config.ls.el8.sh
@@ -14,8 +14,6 @@ pkg_config_dest=(
 
 pkg_depends=(
     "openssl"
-    "libzstd"
-    "lz4"
     "lsphp$php_version_short(api) = $php_api"
     "lsphp$php_version_short-json"
     "lsphp$php_version_short-session"
@@ -24,5 +22,10 @@ pkg_depends=(
 )
 
 fpm_args=(
+  # Relay dlopens these at startup rather than linking them, so they are
+  # wanted but not required. el7 keeps them as hard requires: rpm 4.11
+  # predates weak dependencies and would drop them silently.
+  "--rpm-tag 'Recommends: libzstd'"
+  "--rpm-tag 'Recommends: lz4'"
   "--after-install /root/build/src/rpm/after-install.sh"
 )
diff --git a/build/src/rpm/config.ls.el9.sh b/build/src/rpm/config.ls.el9.sh
index d7a48898..74692ab8 100644
--- a/build/src/rpm/config.ls.el9.sh
+++ b/build/src/rpm/config.ls.el9.sh
@@ -16,8 +16,6 @@ pkg_depends=(
     "openssl"
     # "hiredis >= 1.1.0"
     # "ck >= 0.7.0"
-    "libzstd"
-    "lz4"
     "lsphp$php_version_short(api) = $php_api"
     "lsphp$php_version_short-json"
     "lsphp$php_version_short-session"
@@ -26,5 +24,10 @@ pkg_depends=(
 )
 
 fpm_args=(
+  # Relay dlopens these at startup rather than linking them, so they are
+  # wanted but not required. el7 keeps them as hard requires: rpm 4.11
+  # predates weak dependencies and would drop them silently.
+  "--rpm-tag 'Recommends: libzstd'"
+  "--rpm-tag 'Recommends: lz4'"
   "--after-install /root/build/src/rpm/after-install.sh"
 )
diff --git a/build/src/rpm/config.multi.el8.sh b/build/src/rpm/config.multi.el8.sh
index 9655735f..bd6d6aa2 100644
--- a/build/src/rpm/config.multi.el8.sh
+++ b/build/src/rpm/config.multi.el8.sh
@@ -14,8 +14,6 @@ pkg_config_dest=(
 
 pkg_depends=(
     "openssl"
-    "libzstd"
-    "lz4"
     "php$php_version_short-php(api) = $php_api-64"
     "php$php_version_short-php-json"
     "php$php_version_short-php-session"
@@ -24,5 +22,10 @@ pkg_depends=(
 )
 
 fpm_args=(
+  # Relay dlopens these at startup rather than linking them, so they are
+  # wanted but not required. el7 keeps them as hard requires: rpm 4.11
+  # predates weak dependencies and would drop them silently.
+  "--rpm-tag 'Recommends: libzstd'"
+  "--rpm-tag 'Recommends: lz4'"
   "--after-install /root/build/src/rpm/after-install.sh"
 )
diff --git a/build/src/rpm/config.multi.el9.sh b/build/src/rpm/config.multi.el9.sh
index 7b80f679..9ba9cfa8 100644
--- a/build/src/rpm/config.multi.el9.sh
+++ b/build/src/rpm/config.multi.el9.sh
@@ -16,8 +16,6 @@ pkg_depends=(
     "openssl"
     # "hiredis >= 1.1.0"
     # "ck >= 0.7.0"
-    "libzstd"
-    "lz4"
     "php$php_version_short-php(api) = $php_api-64"
     "php$php_version_short-php-json"
     "php$php_version_short-php-session"
@@ -26,5 +24,10 @@ pkg_depends=(
 )
 
 fpm_args=(
+  # Relay dlopens these at startup rather than linking them, so they are
+  # wanted but not required. el7 keeps them as hard requires: rpm 4.11
+  # predates weak dependencies and would drop them silently.
+  "--rpm-tag 'Recommends: libzstd'"
+  "--rpm-tag 'Recommends: lz4'"
   "--after-install /root/build/src/rpm/after-install.sh"
 )
diff --git a/build/src/rpm/config.single.el8.sh b/build/src/rpm/config.single.el8.sh
index f1efe042..5b09fd12 100644
--- a/build/src/rpm/config.single.el8.sh
+++ b/build/src/rpm/config.single.el8.sh
@@ -16,8 +16,6 @@ pkg_config_dest=(
 
 pkg_depends=(
     "openssl"
-    "libzstd"
-    "lz4"
     "php(api) = $php_api-64"
     "php-json"
     "php-session"
@@ -26,5 +24,10 @@ pkg_depends=(
 )
 
 fpm_args=(
+  # Relay dlopens these at startup rather than linking them, so they are
+  # wanted but not required. el7 keeps them as hard requires: rpm 4.11
+  # predates weak dependencies and would drop them silently.
+  "--rpm-tag 'Recommends: libzstd'"
+  "--rpm-tag 'Recommends: lz4'"
   "--after-install /root/build/src/rpm/after-install.sh"
 )
diff --git a/build/src/rpm/config.single.el9.sh b/build/src/rpm/config.single.el9.sh
index f6cc94ac..cc285d2e 100644
--- a/build/src/rpm/config.single.el9.sh
+++ b/build/src/rpm/config.single.el9.sh
@@ -18,8 +18,6 @@ pkg_depends=(
     "openssl"
     # "hiredis >= 1.1.0"
     # "ck >= 0.7.0"
-    "libzstd"
-    "lz4"
     "php(api) = $php_api-64"
     "php-json"
     "php-session"
@@ -28,5 +26,10 @@ pkg_depends=(
 )
 
 fpm_args=(
+  # Relay dlopens these at startup rather than linking them, so they are
+  # wanted but not required. el7 keeps them as hard requires: rpm 4.11
+  # predates weak dependencies and would drop them silently.
+  "--rpm-tag 'Recommends: libzstd'"
+  "--rpm-tag 'Recommends: lz4'"
   "--after-install /root/build/src/rpm/after-install.sh"
 )

From d3b0183659fc9def0a7585a00ae226ee3494c372 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Till=20Kru=CC=88ss?= <till@kruss.io>
Date: Tue, 28 Jul 2026 13:16:18 -0700
Subject: [PATCH 06/13] Trim comments

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015PwyVggCYKS72z4uS36A2D
---
 build/changelog.sh                  | 25 ++++++++-----------------
 build/helpers.sh                    | 21 ++++++---------------
 build/src/deb/after-remove-multi.sh | 12 +++---------
 build/src/deb/config.base.sh        |  5 ++---
 build/src/deb/config.ls.sh          |  9 +++------
 build/src/deb/config.multi.sh       |  3 +--
 build/src/rpm/config.ls.el8.sh      |  5 ++---
 build/src/rpm/config.ls.el9.sh      |  5 ++---
 build/src/rpm/config.multi.el8.sh   |  5 ++---
 build/src/rpm/config.multi.el9.sh   |  5 ++---
 build/src/rpm/config.single.el8.sh  |  5 ++---
 build/src/rpm/config.single.el9.sh  |  5 ++---
 12 files changed, 35 insertions(+), 70 deletions(-)

diff --git a/build/changelog.sh b/build/changelog.sh
index ac39e338..44d43772 100755
--- a/build/changelog.sh
+++ b/build/changelog.sh
@@ -1,16 +1,11 @@
 #!/bin/bash
 
-# Renders Debian and RPM changelogs from the cachewerk/relay GitHub releases feed.
+# Renders changelogs from the relay GitHub releases feed.
 #
 #   changelog.sh <releases.json> <version> <out_dir>
 #
-# Writes:
-#   $out_dir/changelog.deb.tpl   Debian format, with @PKG@ standing in for the binary
-#                                package name (substituted per package by fpm_build)
-#   $out_dir/changelog.rpm       RPM %changelog format
-#
-# Releases newer than $version are dropped so a rebuild of an older tag does not
-# claim changes it does not contain.
+# Writes changelog.deb.tpl (@PKG@ is substituted per package by fpm_build),
+# changelog.rpm, and changelog.epoch.
 
 set -e
 
@@ -20,8 +15,7 @@ out=$3
 
 maintainer="Relay Team <hello@cachewerk.com>"
 
-# Release notes are written for GitHub and routinely exceed 80 columns, which
-# lintian flags as debian-changelog-line-too-long. Re-wrap the bullet lines.
+# release notes routinely exceed lintian's 80 column limit
 wrap_bullets()
 {
   awk -v prefix="$1" -v cont="$2" -v max=76 '
@@ -38,15 +32,14 @@ wrap_bullets()
     }'
 }
 
-# The topmost entry has to match the version being packaged, so refuse to run
-# rather than emit a changelog that claims the wrong release.
+# the topmost entry has to match the version being packaged
 if ! jq -e --arg v "$version" 'any(.[]; (.draft | not) and (.tag_name | ltrimstr("v")) == $v)' \
      "$releases" > /dev/null; then
   echo "No published release found for $version" >&2
   exit 1
 fi
 
-# Newest first, drop drafts, drop anything above the version being built.
+# newest first, without drafts or anything above the version being built
 filtered=$(jq --arg v "$version" '
   map(select(.draft | not))
   | sort_by(.published_at)
@@ -56,7 +49,7 @@ filtered=$(jq --arg v "$version" '
   | .[$i:]
 ' "$releases")
 
-# Bullet lines out of the Keep-a-Changelog markdown body, "### Added" headings dropped.
+# bullet lines only, headings dropped
 bullets='
   (.body // "")
   | gsub("\r"; "")
@@ -87,9 +80,7 @@ echo "$filtered" | jq -r --arg m "$maintainer" "
     + \"\n\"
 " | wrap_bullets "- " "  " > "$out/changelog.rpm"
 
-# Timestamp of the release being packaged. fpm stamps the gzipped changelog with
-# the source date epoch, and lintian flags the package when that is newer than
-# the newest changelog entry, so the two have to come from the same place.
+# the source date epoch must not be newer than the newest changelog entry
 echo "$filtered" | jq -r '.[0].published_at | fromdateiso8601' > "$out/changelog.epoch"
 
 echo "Wrote $(grep -c '^@PKG@' "$out/changelog.deb.tpl") deb entries, $(grep -c '^\* ' "$out/changelog.rpm") rpm entries"
diff --git a/build/helpers.sh b/build/helpers.sh
index e6c7beff..91a56e54 100755
--- a/build/helpers.sh
+++ b/build/helpers.sh
@@ -1,5 +1,5 @@
 
-# NOTE: must NOT be named pkg_*, main() runs `unset ${!pkg_@}` before every build
+# must not be named pkg_*, main() unsets those before every build
 read -r -d '' relay_description <<'DESCRIPTION' || true
 Next-generation caching layer for PHP
 Relay is a fast, persistent, in-memory cache for PHP that serves as a drop-in
@@ -66,8 +66,6 @@ fpm_build()
     cp $src_path/relay.ini $dest_path/$config_file
   done
 
-  # Debian policy requires /usr/share/doc/<pkg>/copyright; rpm wants documentation.
-  # The year comes from the release date so the file stays reproducible.
   mkdir -p $dest_path/usr/share/doc/$pkg_name
   {
     echo "Copyright (C) 2021-$(date -u -d @$(cat /root/build/changelog.epoch) +%Y) CacheWerk, Inc."
@@ -78,9 +76,7 @@ fpm_build()
     echo
     cat $src_path/LICENSE
 
-    # relay-pkg.so statically links hiredis and ck, so their notices have to
-    # ship with it. The plain relay.so links both dynamically and is covered by
-    # the distribution's own packages. lz4 and zstd are dlopen'd either way.
+    # only the -pkg builds statically link these
     if [[ "$pkg_binary" == *-pkg* ]]; then
       for bundled in hiredis ck; do
         echo
@@ -91,16 +87,13 @@ fpm_build()
         cat /root/build/licenses/$bundled.txt
       done
 
-      # ck carries an Apache-2.0 notice for src/ck_hp.c. Debian policy wants the
-      # shipped copy referenced rather than the notice standing alone.
+      # ck's notice for src/ck_hp.c is Apache-2.0, which must reference the shipped copy
       echo
       echo "On Debian systems the complete text of the Apache License, Version 2.0"
       echo "can be found in /usr/share/common-licenses/Apache-2.0."
     fi
   } > $dest_path/usr/share/doc/$pkg_name/copyright
 
-  # Tags that are correct behaviour here and cannot be resolved without breaking
-  # the package, declared so they stop being reported as defects.
   if [[ "$type" == "deb" && ${#pkg_lintian_overrides[@]} -gt 0 ]]; then
     mkdir -p $dest_path/usr/share/lintian/overrides
     for tag in "${pkg_lintian_overrides[@]}"; do
@@ -134,17 +127,15 @@ fpm_build()
     "--deb-no-default-config-files"
   )
 
-  # `Vendor` is a real rpm tag but not a valid Debian control field. fpm guards
-  # the deb line with `!vendor.empty?`, so an explicit empty value omits it.
-  # Don't try the same on --license: that line is emitted unconditionally, so an
-  # empty value adds `empty-field` on top of the existing `unknown-field`.
+  # deb has no Vendor field; an empty value omits it. Don't do the same for
+  # --license, fpm emits that line unconditionally and it'd end up empty.
   if [[ "$type" == "rpm" ]]; then
     args+=("--vendor 'CacheWerk, Inc.'")
   else
     args+=("--vendor ''")
   fi
 
-  # changelogs: deb entries embed the binary package name, rpm entries do not
+  # deb changelog entries embed the package name, rpm ones don't
   if [[ "$type" == "deb" ]]; then
     sed "s/@PKG@/$pkg_name/g" /root/build/changelog.deb.tpl > /tmp/changelog-$pkg_name.deb
     args+=("--deb-changelog /tmp/changelog-$pkg_name.deb")
diff --git a/build/src/deb/after-remove-multi.sh b/build/src/deb/after-remove-multi.sh
index deeea9b6..c1eca164 100644
--- a/build/src/deb/after-remove-multi.sh
+++ b/build/src/deb/after-remove-multi.sh
@@ -2,12 +2,8 @@
 
 set -e
 
-# Counterpart to after-install-multi.sh, which enables the module. Without this,
-# removing the package leaves relay enabled and PHP loads a relay.so that is no
-# longer there. Mirrors what Debian's own PHP extension packages do in postrm.
-#
-# Nothing here may abort the removal, so every call tolerates failure: by the
-# time this runs the PHP tooling may already be gone.
+# Undoes after-install-multi.sh. Failures are tolerated throughout: the PHP
+# tooling may already be gone, and nothing here may block the removal.
 
 if [ "$1" = "remove" ]; then
   if [ -e /usr/lib/php/php-maintscript-helper ]; then
@@ -18,9 +14,7 @@ if [ "$1" = "remove" ]; then
   fi
 fi
 
-# dpkg removes the conffile itself, but the symlinks phpenmod created are not
-# owned by the package. Sweep any that still point at our ini, which is what is
-# left behind when the helper above was already unavailable.
+# dpkg owns the conffile, but not the symlinks phpenmod created
 if [ "$1" = "purge" ]; then
   find "/etc/php/<%= php_version %>" -type l 2>/dev/null | while read -r symlink; do
     if [ "$(basename "$(readlink -m "${symlink}")")" = "relay.ini" ]; then
diff --git a/build/src/deb/config.base.sh b/build/src/deb/config.base.sh
index 5ba3fedd..62e13c7e 100644
--- a/build/src/deb/config.base.sh
+++ b/build/src/deb/config.base.sh
@@ -25,8 +25,7 @@ fpm_args=(
   "--deb-pre-depends 'php-common'"
   "--after-install /root/build/src/deb/after-install.sh"
 
-  # This package ships no files of its own. The word "metapackage" is what tells
-  # lintian to skip its empty-package and arch-dependent-files checks, so keep
-  # it. The $'...' quoting is required: fpm does not expand \n in --description.
+  # ships no files; the word "metapackage" is what makes lintian skip its
+  # empty-package checks, and $'...' is required since fpm won't expand \n
   "--description $'Relay metapackage for PHP $php_version\nThis dependency metapackage pulls in the Relay extension for PHP\n$php_version along with its companion extensions.'"
 )
diff --git a/build/src/deb/config.ls.sh b/build/src/deb/config.ls.sh
index 4d8f223e..9970b287 100644
--- a/build/src/deb/config.ls.sh
+++ b/build/src/deb/config.ls.sh
@@ -30,10 +30,8 @@ pkg_depends=(
   "libck0 >= 0.7.0"
 )
 
-# LiteSpeed keeps its bundled PHP under /usr/local, so these packages cannot
-# follow the FHS the way the regular ones do. The ini has to stay a conffile
-# despite living outside /etc, or a user's settings would be overwritten on
-# every upgrade.
+# LiteSpeed keeps its bundled PHP under /usr/local, and the ini must stay a
+# conffile there or user settings are lost on upgrade
 pkg_lintian_overrides=(
   "dir-in-usr-local"
   "file-in-usr-local"
@@ -43,8 +41,7 @@ pkg_lintian_overrides=(
 )
 
 fpm_args=(
-  # Relay dlopens these at startup rather than linking them, so they are
-  # wanted but not required.
+  # dlopen'd at startup, not linked
   "--deb-recommends 'liblz4-1 (>= 0.0~r130)'"
   "--deb-recommends 'libzstd1 (>= 1.3.2)'"
   "--after-install /root/build/src/deb/after-install.sh"
diff --git a/build/src/deb/config.multi.sh b/build/src/deb/config.multi.sh
index 27be25b8..51d332bd 100644
--- a/build/src/deb/config.multi.sh
+++ b/build/src/deb/config.multi.sh
@@ -32,8 +32,7 @@ pkg_depends=(
 )
 
 fpm_args=(
-  # Relay dlopens these at startup rather than linking them, so they are
-  # wanted but not required.
+  # dlopen'd at startup, not linked
   "--deb-recommends 'liblz4-1 (>= 0.0~r130)'"
   "--deb-recommends 'libzstd1 (>= 1.3.2)'"
   "--replaces 'php-relay << ${version#v}'"
diff --git a/build/src/rpm/config.ls.el8.sh b/build/src/rpm/config.ls.el8.sh
index 998d2440..f716bce8 100644
--- a/build/src/rpm/config.ls.el8.sh
+++ b/build/src/rpm/config.ls.el8.sh
@@ -22,9 +22,8 @@ pkg_depends=(
 )
 
 fpm_args=(
-  # Relay dlopens these at startup rather than linking them, so they are
-  # wanted but not required. el7 keeps them as hard requires: rpm 4.11
-  # predates weak dependencies and would drop them silently.
+  # dlopen'd at startup, not linked; el7 keeps them as requires, rpm 4.11
+  # predates weak dependencies
   "--rpm-tag 'Recommends: libzstd'"
   "--rpm-tag 'Recommends: lz4'"
   "--after-install /root/build/src/rpm/after-install.sh"
diff --git a/build/src/rpm/config.ls.el9.sh b/build/src/rpm/config.ls.el9.sh
index 74692ab8..04dd86fd 100644
--- a/build/src/rpm/config.ls.el9.sh
+++ b/build/src/rpm/config.ls.el9.sh
@@ -24,9 +24,8 @@ pkg_depends=(
 )
 
 fpm_args=(
-  # Relay dlopens these at startup rather than linking them, so they are
-  # wanted but not required. el7 keeps them as hard requires: rpm 4.11
-  # predates weak dependencies and would drop them silently.
+  # dlopen'd at startup, not linked; el7 keeps them as requires, rpm 4.11
+  # predates weak dependencies
   "--rpm-tag 'Recommends: libzstd'"
   "--rpm-tag 'Recommends: lz4'"
   "--after-install /root/build/src/rpm/after-install.sh"
diff --git a/build/src/rpm/config.multi.el8.sh b/build/src/rpm/config.multi.el8.sh
index bd6d6aa2..880179cb 100644
--- a/build/src/rpm/config.multi.el8.sh
+++ b/build/src/rpm/config.multi.el8.sh
@@ -22,9 +22,8 @@ pkg_depends=(
 )
 
 fpm_args=(
-  # Relay dlopens these at startup rather than linking them, so they are
-  # wanted but not required. el7 keeps them as hard requires: rpm 4.11
-  # predates weak dependencies and would drop them silently.
+  # dlopen'd at startup, not linked; el7 keeps them as requires, rpm 4.11
+  # predates weak dependencies
   "--rpm-tag 'Recommends: libzstd'"
   "--rpm-tag 'Recommends: lz4'"
   "--after-install /root/build/src/rpm/after-install.sh"
diff --git a/build/src/rpm/config.multi.el9.sh b/build/src/rpm/config.multi.el9.sh
index 9ba9cfa8..68ebce2d 100644
--- a/build/src/rpm/config.multi.el9.sh
+++ b/build/src/rpm/config.multi.el9.sh
@@ -24,9 +24,8 @@ pkg_depends=(
 )
 
 fpm_args=(
-  # Relay dlopens these at startup rather than linking them, so they are
-  # wanted but not required. el7 keeps them as hard requires: rpm 4.11
-  # predates weak dependencies and would drop them silently.
+  # dlopen'd at startup, not linked; el7 keeps them as requires, rpm 4.11
+  # predates weak dependencies
   "--rpm-tag 'Recommends: libzstd'"
   "--rpm-tag 'Recommends: lz4'"
   "--after-install /root/build/src/rpm/after-install.sh"
diff --git a/build/src/rpm/config.single.el8.sh b/build/src/rpm/config.single.el8.sh
index 5b09fd12..aef0c940 100644
--- a/build/src/rpm/config.single.el8.sh
+++ b/build/src/rpm/config.single.el8.sh
@@ -24,9 +24,8 @@ pkg_depends=(
 )
 
 fpm_args=(
-  # Relay dlopens these at startup rather than linking them, so they are
-  # wanted but not required. el7 keeps them as hard requires: rpm 4.11
-  # predates weak dependencies and would drop them silently.
+  # dlopen'd at startup, not linked; el7 keeps them as requires, rpm 4.11
+  # predates weak dependencies
   "--rpm-tag 'Recommends: libzstd'"
   "--rpm-tag 'Recommends: lz4'"
   "--after-install /root/build/src/rpm/after-install.sh"
diff --git a/build/src/rpm/config.single.el9.sh b/build/src/rpm/config.single.el9.sh
index cc285d2e..db43b18e 100644
--- a/build/src/rpm/config.single.el9.sh
+++ b/build/src/rpm/config.single.el9.sh
@@ -26,9 +26,8 @@ pkg_depends=(
 )
 
 fpm_args=(
-  # Relay dlopens these at startup rather than linking them, so they are
-  # wanted but not required. el7 keeps them as hard requires: rpm 4.11
-  # predates weak dependencies and would drop them silently.
+  # dlopen'd at startup, not linked; el7 keeps them as requires, rpm 4.11
+  # predates weak dependencies
   "--rpm-tag 'Recommends: libzstd'"
   "--rpm-tag 'Recommends: lz4'"
   "--after-install /root/build/src/rpm/after-install.sh"

From d1b25153d2152192fcd14c73f650b5e0fc5e1427 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Till=20Kr=C3=BCss?= <tillkruss@users.noreply.github.com>
Date: Tue, 28 Jul 2026 13:17:02 -0700
Subject: [PATCH 07/13] Update package.yml

---
 .github/workflows/package.yml | 1 -
 1 file changed, 1 deletion(-)

diff --git a/.github/workflows/package.yml b/.github/workflows/package.yml
index 94908407..055ae81f 100644
--- a/.github/workflows/package.yml
+++ b/.github/workflows/package.yml
@@ -36,7 +36,6 @@ jobs:
           docker pull ghcr.io/${{ github.repository_owner }}/fpm:latest
           docker tag ghcr.io/${{ github.repository_owner }}/fpm:latest fpm
 
-      # Rendered on the runner rather than inside the container, which has no jq
       - name: Render changelogs
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

From c5ad7da9e979763c9896f843de9bf7828ff71452 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Till=20Kr=C3=BCss?= <tillkruss@users.noreply.github.com>
Date: Tue, 28 Jul 2026 13:17:58 -0700
Subject: [PATCH 08/13] Modify fpm_args description for PHP metapackage

Updated the description in fpm_args to remove mention of companion extensions.
---
 build/src/deb/config.base.sh | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/build/src/deb/config.base.sh b/build/src/deb/config.base.sh
index 62e13c7e..1b0cb005 100644
--- a/build/src/deb/config.base.sh
+++ b/build/src/deb/config.base.sh
@@ -24,8 +24,5 @@ pkg_depends=(
 fpm_args=(
   "--deb-pre-depends 'php-common'"
   "--after-install /root/build/src/deb/after-install.sh"
-
-  # ships no files; the word "metapackage" is what makes lintian skip its
-  # empty-package checks, and $'...' is required since fpm won't expand \n
-  "--description $'Relay metapackage for PHP $php_version\nThis dependency metapackage pulls in the Relay extension for PHP\n$php_version along with its companion extensions.'"
+  "--description $'Relay metapackage for PHP $php_version\nThis dependency metapackage pulls in the Relay extension for PHP\n$php_version.'"
 )

From 915be9dfdf1abb6f405dc0b31593b39dc1300275 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Till=20Kru=CC=88ss?= <till@kruss.io>
Date: Tue, 28 Jul 2026 13:19:05 -0700
Subject: [PATCH 09/13] Note the Relay version that made lz4 and zstd optional

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015PwyVggCYKS72z4uS36A2D
---
 build/src/deb/config.ls.sh         | 2 +-
 build/src/deb/config.multi.sh      | 2 +-
 build/src/rpm/config.ls.el8.sh     | 4 ++--
 build/src/rpm/config.ls.el9.sh     | 4 ++--
 build/src/rpm/config.multi.el8.sh  | 4 ++--
 build/src/rpm/config.multi.el9.sh  | 4 ++--
 build/src/rpm/config.single.el8.sh | 4 ++--
 build/src/rpm/config.single.el9.sh | 4 ++--
 8 files changed, 14 insertions(+), 14 deletions(-)

diff --git a/build/src/deb/config.ls.sh b/build/src/deb/config.ls.sh
index 9970b287..b50c459d 100644
--- a/build/src/deb/config.ls.sh
+++ b/build/src/deb/config.ls.sh
@@ -41,7 +41,7 @@ pkg_lintian_overrides=(
 )
 
 fpm_args=(
-  # dlopen'd at startup, not linked
+  # dlopen'd at startup since Relay v0.40.0, not linked
   "--deb-recommends 'liblz4-1 (>= 0.0~r130)'"
   "--deb-recommends 'libzstd1 (>= 1.3.2)'"
   "--after-install /root/build/src/deb/after-install.sh"
diff --git a/build/src/deb/config.multi.sh b/build/src/deb/config.multi.sh
index 51d332bd..ae29c96d 100644
--- a/build/src/deb/config.multi.sh
+++ b/build/src/deb/config.multi.sh
@@ -32,7 +32,7 @@ pkg_depends=(
 )
 
 fpm_args=(
-  # dlopen'd at startup, not linked
+  # dlopen'd at startup since Relay v0.40.0, not linked
   "--deb-recommends 'liblz4-1 (>= 0.0~r130)'"
   "--deb-recommends 'libzstd1 (>= 1.3.2)'"
   "--replaces 'php-relay << ${version#v}'"
diff --git a/build/src/rpm/config.ls.el8.sh b/build/src/rpm/config.ls.el8.sh
index f716bce8..51ac1a53 100644
--- a/build/src/rpm/config.ls.el8.sh
+++ b/build/src/rpm/config.ls.el8.sh
@@ -22,8 +22,8 @@ pkg_depends=(
 )
 
 fpm_args=(
-  # dlopen'd at startup, not linked; el7 keeps them as requires, rpm 4.11
-  # predates weak dependencies
+  # dlopen'd at startup since Relay v0.40.0, not linked; el7 keeps them as
+  # requires, rpm 4.11 predates weak dependencies
   "--rpm-tag 'Recommends: libzstd'"
   "--rpm-tag 'Recommends: lz4'"
   "--after-install /root/build/src/rpm/after-install.sh"
diff --git a/build/src/rpm/config.ls.el9.sh b/build/src/rpm/config.ls.el9.sh
index 04dd86fd..127dbbd3 100644
--- a/build/src/rpm/config.ls.el9.sh
+++ b/build/src/rpm/config.ls.el9.sh
@@ -24,8 +24,8 @@ pkg_depends=(
 )
 
 fpm_args=(
-  # dlopen'd at startup, not linked; el7 keeps them as requires, rpm 4.11
-  # predates weak dependencies
+  # dlopen'd at startup since Relay v0.40.0, not linked; el7 keeps them as
+  # requires, rpm 4.11 predates weak dependencies
   "--rpm-tag 'Recommends: libzstd'"
   "--rpm-tag 'Recommends: lz4'"
   "--after-install /root/build/src/rpm/after-install.sh"
diff --git a/build/src/rpm/config.multi.el8.sh b/build/src/rpm/config.multi.el8.sh
index 880179cb..c62ed1bb 100644
--- a/build/src/rpm/config.multi.el8.sh
+++ b/build/src/rpm/config.multi.el8.sh
@@ -22,8 +22,8 @@ pkg_depends=(
 )
 
 fpm_args=(
-  # dlopen'd at startup, not linked; el7 keeps them as requires, rpm 4.11
-  # predates weak dependencies
+  # dlopen'd at startup since Relay v0.40.0, not linked; el7 keeps them as
+  # requires, rpm 4.11 predates weak dependencies
   "--rpm-tag 'Recommends: libzstd'"
   "--rpm-tag 'Recommends: lz4'"
   "--after-install /root/build/src/rpm/after-install.sh"
diff --git a/build/src/rpm/config.multi.el9.sh b/build/src/rpm/config.multi.el9.sh
index 68ebce2d..12684875 100644
--- a/build/src/rpm/config.multi.el9.sh
+++ b/build/src/rpm/config.multi.el9.sh
@@ -24,8 +24,8 @@ pkg_depends=(
 )
 
 fpm_args=(
-  # dlopen'd at startup, not linked; el7 keeps them as requires, rpm 4.11
-  # predates weak dependencies
+  # dlopen'd at startup since Relay v0.40.0, not linked; el7 keeps them as
+  # requires, rpm 4.11 predates weak dependencies
   "--rpm-tag 'Recommends: libzstd'"
   "--rpm-tag 'Recommends: lz4'"
   "--after-install /root/build/src/rpm/after-install.sh"
diff --git a/build/src/rpm/config.single.el8.sh b/build/src/rpm/config.single.el8.sh
index aef0c940..a039b0c1 100644
--- a/build/src/rpm/config.single.el8.sh
+++ b/build/src/rpm/config.single.el8.sh
@@ -24,8 +24,8 @@ pkg_depends=(
 )
 
 fpm_args=(
-  # dlopen'd at startup, not linked; el7 keeps them as requires, rpm 4.11
-  # predates weak dependencies
+  # dlopen'd at startup since Relay v0.40.0, not linked; el7 keeps them as
+  # requires, rpm 4.11 predates weak dependencies
   "--rpm-tag 'Recommends: libzstd'"
   "--rpm-tag 'Recommends: lz4'"
   "--after-install /root/build/src/rpm/after-install.sh"
diff --git a/build/src/rpm/config.single.el9.sh b/build/src/rpm/config.single.el9.sh
index db43b18e..51a43cd2 100644
--- a/build/src/rpm/config.single.el9.sh
+++ b/build/src/rpm/config.single.el9.sh
@@ -26,8 +26,8 @@ pkg_depends=(
 )
 
 fpm_args=(
-  # dlopen'd at startup, not linked; el7 keeps them as requires, rpm 4.11
-  # predates weak dependencies
+  # dlopen'd at startup since Relay v0.40.0, not linked; el7 keeps them as
+  # requires, rpm 4.11 predates weak dependencies
   "--rpm-tag 'Recommends: libzstd'"
   "--rpm-tag 'Recommends: lz4'"
   "--after-install /root/build/src/rpm/after-install.sh"

From c29d4895238861958705ace819d0011939b1de25 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Till=20Kru=CC=88ss?= <till@kruss.io>
Date: Tue, 28 Jul 2026 13:22:07 -0700
Subject: [PATCH 10/13] wip

---
 build/src/rpm/config.ls.el8.sh     | 3 +--
 build/src/rpm/config.ls.el9.sh     | 3 +--
 build/src/rpm/config.multi.el8.sh  | 3 +--
 build/src/rpm/config.multi.el9.sh  | 3 +--
 build/src/rpm/config.single.el8.sh | 3 +--
 build/src/rpm/config.single.el9.sh | 3 +--
 6 files changed, 6 insertions(+), 12 deletions(-)

diff --git a/build/src/rpm/config.ls.el8.sh b/build/src/rpm/config.ls.el8.sh
index 51ac1a53..432ec162 100644
--- a/build/src/rpm/config.ls.el8.sh
+++ b/build/src/rpm/config.ls.el8.sh
@@ -22,8 +22,7 @@ pkg_depends=(
 )
 
 fpm_args=(
-  # dlopen'd at startup since Relay v0.40.0, not linked; el7 keeps them as
-  # requires, rpm 4.11 predates weak dependencies
+  # dlopen'd at startup since Relay v0.40.0, not linked
   "--rpm-tag 'Recommends: libzstd'"
   "--rpm-tag 'Recommends: lz4'"
   "--after-install /root/build/src/rpm/after-install.sh"
diff --git a/build/src/rpm/config.ls.el9.sh b/build/src/rpm/config.ls.el9.sh
index 127dbbd3..7252c9c8 100644
--- a/build/src/rpm/config.ls.el9.sh
+++ b/build/src/rpm/config.ls.el9.sh
@@ -24,8 +24,7 @@ pkg_depends=(
 )
 
 fpm_args=(
-  # dlopen'd at startup since Relay v0.40.0, not linked; el7 keeps them as
-  # requires, rpm 4.11 predates weak dependencies
+  # dlopen'd at startup since Relay v0.40.0, not linked
   "--rpm-tag 'Recommends: libzstd'"
   "--rpm-tag 'Recommends: lz4'"
   "--after-install /root/build/src/rpm/after-install.sh"
diff --git a/build/src/rpm/config.multi.el8.sh b/build/src/rpm/config.multi.el8.sh
index c62ed1bb..3ba100d8 100644
--- a/build/src/rpm/config.multi.el8.sh
+++ b/build/src/rpm/config.multi.el8.sh
@@ -22,8 +22,7 @@ pkg_depends=(
 )
 
 fpm_args=(
-  # dlopen'd at startup since Relay v0.40.0, not linked; el7 keeps them as
-  # requires, rpm 4.11 predates weak dependencies
+  # dlopen'd at startup since Relay v0.40.0, not linked
   "--rpm-tag 'Recommends: libzstd'"
   "--rpm-tag 'Recommends: lz4'"
   "--after-install /root/build/src/rpm/after-install.sh"
diff --git a/build/src/rpm/config.multi.el9.sh b/build/src/rpm/config.multi.el9.sh
index 12684875..c34e5cca 100644
--- a/build/src/rpm/config.multi.el9.sh
+++ b/build/src/rpm/config.multi.el9.sh
@@ -24,8 +24,7 @@ pkg_depends=(
 )
 
 fpm_args=(
-  # dlopen'd at startup since Relay v0.40.0, not linked; el7 keeps them as
-  # requires, rpm 4.11 predates weak dependencies
+  # dlopen'd at startup since Relay v0.40.0, not linked
   "--rpm-tag 'Recommends: libzstd'"
   "--rpm-tag 'Recommends: lz4'"
   "--after-install /root/build/src/rpm/after-install.sh"
diff --git a/build/src/rpm/config.single.el8.sh b/build/src/rpm/config.single.el8.sh
index a039b0c1..7ebe6060 100644
--- a/build/src/rpm/config.single.el8.sh
+++ b/build/src/rpm/config.single.el8.sh
@@ -24,8 +24,7 @@ pkg_depends=(
 )
 
 fpm_args=(
-  # dlopen'd at startup since Relay v0.40.0, not linked; el7 keeps them as
-  # requires, rpm 4.11 predates weak dependencies
+  # dlopen'd at startup since Relay v0.40.0, not linked
   "--rpm-tag 'Recommends: libzstd'"
   "--rpm-tag 'Recommends: lz4'"
   "--after-install /root/build/src/rpm/after-install.sh"
diff --git a/build/src/rpm/config.single.el9.sh b/build/src/rpm/config.single.el9.sh
index 51a43cd2..5d9dc247 100644
--- a/build/src/rpm/config.single.el9.sh
+++ b/build/src/rpm/config.single.el9.sh
@@ -26,8 +26,7 @@ pkg_depends=(
 )
 
 fpm_args=(
-  # dlopen'd at startup since Relay v0.40.0, not linked; el7 keeps them as
-  # requires, rpm 4.11 predates weak dependencies
+  # dlopen'd at startup since Relay v0.40.0, not linked
   "--rpm-tag 'Recommends: libzstd'"
   "--rpm-tag 'Recommends: lz4'"
   "--after-install /root/build/src/rpm/after-install.sh"

From 1f8d019221c7e02cf3a75443c004b416d5ab8171 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Till=20Kru=CC=88ss?= <till@kruss.io>
Date: Tue, 28 Jul 2026 13:29:09 -0700
Subject: [PATCH 11/13] Rewrite the package description

Leads with the product positioning rather than a generic summary.

The synopsis keeps its leading article and trailing period, so
description-synopsis-starts-with-article, synopsis-is-a-sentence and
summary-ended-with-dot are reported again. Debian wants a noun phrase
there; dropping "The" and the period would clear all three.

Note the text has to stay ASCII. A multiplication sign in the description
aborts every rpm build -- fpm's rpm.erb raises Encoding::CompatibilityError
mixing ASCII-8BIT and US-ASCII once a changelog is attached.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015PwyVggCYKS72z4uS36A2D
---
 build/helpers.sh | 17 ++++++++---------
 1 file changed, 8 insertions(+), 9 deletions(-)

diff --git a/build/helpers.sh b/build/helpers.sh
index 91a56e54..2ba9a5d8 100755
--- a/build/helpers.sh
+++ b/build/helpers.sh
@@ -1,11 +1,10 @@
 
 # must not be named pkg_*, main() unsets those before every build
 read -r -d '' relay_description <<'DESCRIPTION' || true
-Next-generation caching layer for PHP
-Relay is a fast, persistent, in-memory cache for PHP that serves as a drop-in
-replacement for PhpRedis. It keeps a partial replica of the Redis or Valkey
-data set inside the PHP process, avoiding network round trips and decoding
-costs for cached keys.
+The Fastest Redis client for PHP.
+100x faster cache reads, near-zero bandwidth, no code changes required.
+Relay keeps a partial replica of the Redis or Valkey data set inside the
+PHP process, avoiding network round trips.
 DESCRIPTION
 
 main()
@@ -68,7 +67,7 @@ fpm_build()
 
   mkdir -p $dest_path/usr/share/doc/$pkg_name
   {
-    echo "Copyright (C) 2021-$(date -u -d @$(cat /root/build/changelog.epoch) +%Y) CacheWerk, Inc."
+    echo "Copyright (C) 2021-$(date -u -d @$(cat /root/build/changelog/epoch) +%Y) CacheWerk, Inc."
     echo "All rights reserved."
     echo
     echo "Relay is proprietary software, licensed under the End-User License"
@@ -118,7 +117,7 @@ fpm_build()
     "--architecture $pkg_arch"
 
     "--package dist/$pkg_filename"
-    "--source-date-epoch-default $(cat /root/build/changelog.epoch)"
+    "--source-date-epoch-default $(cat /root/build/changelog/epoch)"
 
     "--template-value binary_paths='$pkg_binary_dest'"
     "--template-value php_version='$php_version'"
@@ -137,10 +136,10 @@ fpm_build()
 
   # deb changelog entries embed the package name, rpm ones don't
   if [[ "$type" == "deb" ]]; then
-    sed "s/@PKG@/$pkg_name/g" /root/build/changelog.deb.tpl > /tmp/changelog-$pkg_name.deb
+    sed "s/@PKG@/$pkg_name/g" /root/build/changelog/deb.tpl > /tmp/changelog-$pkg_name.deb
     args+=("--deb-changelog /tmp/changelog-$pkg_name.deb")
   else
-    args+=("--rpm-changelog /root/build/changelog.rpm")
+    args+=("--rpm-changelog /root/build/changelog/rpm")
   fi
 
   if [ ! -z "$pkg_provides" ]; then

From 7c6c62ac20dd58c0ce20b721111f7ab04dd6a3e2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Till=20Kru=CC=88ss?= <till@kruss.io>
Date: Tue, 28 Jul 2026 13:29:17 -0700
Subject: [PATCH 12/13] Collapse gitignore entries

Generated changelogs now land in build/changelog/ as deb.tpl, rpm and
epoch, so they need one ignore rule instead of three. They could not be
globbed where they were: /build/changelog.* would also have matched the
tracked changelog.sh.

The two per-format source rules fold into one glob. Seven entries become
four, all still needed.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015PwyVggCYKS72z4uS36A2D
---
 .github/workflows/package.yml |  2 +-
 .gitignore                    |  7 ++-----
 build/changelog.sh            | 14 ++++++++------
 3 files changed, 11 insertions(+), 12 deletions(-)

diff --git a/.github/workflows/package.yml b/.github/workflows/package.yml
index 055ae81f..a55f3f82 100644
--- a/.github/workflows/package.yml
+++ b/.github/workflows/package.yml
@@ -42,7 +42,7 @@ jobs:
         run: |
           gh api --paginate 'repos/${{ github.repository_owner }}/relay/releases?per_page=100' \
             | jq -s 'add' > /tmp/releases.json
-          ./build/changelog.sh /tmp/releases.json '${{ github.event.inputs.tag }}' build
+          ./build/changelog.sh /tmp/releases.json '${{ github.event.inputs.tag }}' build/changelog
 
       - name: Bundle packages
         run: |
diff --git a/.gitignore b/.gitignore
index 72f06f4c..cbe33068 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,7 +1,4 @@
 /build/dist
-/build/src/deb/*-php*
-/build/src/rpm/*-php*
+/build/src/*/*-php*
+/build/changelog/
 key-private.asc
-/build/changelog.deb.tpl
-/build/changelog.rpm
-/build/changelog.epoch
diff --git a/build/changelog.sh b/build/changelog.sh
index 44d43772..f8ee9468 100755
--- a/build/changelog.sh
+++ b/build/changelog.sh
@@ -4,8 +4,8 @@
 #
 #   changelog.sh <releases.json> <version> <out_dir>
 #
-# Writes changelog.deb.tpl (@PKG@ is substituted per package by fpm_build),
-# changelog.rpm, and changelog.epoch.
+# Writes deb.tpl (@PKG@ is substituted per package by fpm_build), rpm and
+# epoch into <out_dir>.
 
 set -e
 
@@ -13,6 +13,8 @@ releases=$1
 version=${2#v}
 out=$3
 
+mkdir -p "$out"
+
 maintainer="Relay Team <hello@cachewerk.com>"
 
 # release notes routinely exceed lintian's 80 column limit
@@ -68,7 +70,7 @@ echo "$filtered" | jq -r --arg m "$maintainer" "
     + \"\n\n -- \" + \$m + \"  \"
     + (.published_at | fromdateiso8601 | strftime(\"%a, %d %b %Y %H:%M:%S +0000\"))
     + \"\n\"
-" | wrap_bullets "  * " "    " > "$out/changelog.deb.tpl"
+" | wrap_bullets "  * " "    " > "$out/deb.tpl"
 
 echo "$filtered" | jq -r --arg m "$maintainer" "
   .[]
@@ -78,9 +80,9 @@ echo "$filtered" | jq -r --arg m "$maintainer" "
     + \" \" + \$m + \" - \" + .ver + \"-1\n\"
     + (\$b | map(\"- \" + .) | join(\"\n\"))
     + \"\n\"
-" | wrap_bullets "- " "  " > "$out/changelog.rpm"
+" | wrap_bullets "- " "  " > "$out/rpm"
 
 # the source date epoch must not be newer than the newest changelog entry
-echo "$filtered" | jq -r '.[0].published_at | fromdateiso8601' > "$out/changelog.epoch"
+echo "$filtered" | jq -r '.[0].published_at | fromdateiso8601' > "$out/epoch"
 
-echo "Wrote $(grep -c '^@PKG@' "$out/changelog.deb.tpl") deb entries, $(grep -c '^\* ' "$out/changelog.rpm") rpm entries"
+echo "Wrote $(grep -c '^@PKG@' "$out/deb.tpl") deb entries, $(grep -c '^\* ' "$out/rpm") rpm entries"

From 929468b9ee717ced5be732c3786d7b67fb5cef75 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Till=20Kru=CC=88ss?= <till@kruss.io>
Date: Tue, 28 Jul 2026 13:34:38 -0700
Subject: [PATCH 13/13] Make the synopsis a noun phrase and harden changelog.sh

Drops the leading article and trailing period, which Debian disallows in
a synopsis. Clears description-synopsis-starts-with-article,
synopsis-is-a-sentence and summary-ended-with-dot.

changelog.sh gains -u and -o pipefail. pipefail is the one that matters:
every output file is written through `jq | wrap_bullets`, and awk exits 0
regardless, so a jq failure would leave a silently truncated changelog
and the script would carry on. Reproduced before fixing. -u turns a
missing argument into an immediate error instead of an empty path.

Not applied elsewhere: helpers.sh reads unset variables by design
(pkg_provides, pkg_lintian_overrides), and after-remove-multi.sh must
never abort a package removal.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015PwyVggCYKS72z4uS36A2D
---
 build/changelog.sh | 2 +-
 build/helpers.sh   | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/build/changelog.sh b/build/changelog.sh
index f8ee9468..f95df9d5 100755
--- a/build/changelog.sh
+++ b/build/changelog.sh
@@ -7,7 +7,7 @@
 # Writes deb.tpl (@PKG@ is substituted per package by fpm_build), rpm and
 # epoch into <out_dir>.
 
-set -e
+set -euo pipefail
 
 releases=$1
 version=${2#v}
diff --git a/build/helpers.sh b/build/helpers.sh
index 2ba9a5d8..adf9b681 100755
--- a/build/helpers.sh
+++ b/build/helpers.sh
@@ -1,7 +1,7 @@
 
 # must not be named pkg_*, main() unsets those before every build
 read -r -d '' relay_description <<'DESCRIPTION' || true
-The Fastest Redis client for PHP.
+Fastest Redis client for PHP
 100x faster cache reads, near-zero bandwidth, no code changes required.
 Relay keeps a partial replica of the Redis or Valkey data set inside the
 PHP process, avoiding network round trips.