[joshschmelzle]

Corrects the packaging, release, install, and repository-snapshot guidance so it matches Debian Trixie (Bookworm where a suite difference is real) and the way the active WLAN-Pi repos should be packaged. Current gaps stay in REPOS.md as deviations, not as if they were already done.

Merged main (including the pre-release version gate from #44) with a merge commit. The only conflict was the changelog paragraph in RELEASE_PROCESS.md. The resolution keeps the native major.minor.patch scheme and sets the same major.minor.patch and pre-release in __version__.py.

Review order

627 changed lines against main, one outcome: the docs describe one packaging scheme and the snapshot matches the default branches checked on 2026-10-22. Splitting would leave the example, the policy, and the deviation list disagreeing with each other.

1. architecture/PACKAGING.md — the scheme (compat, source format and version, runtime vs test deps, unit path, maintainer scripts, /opt override, reusable workflows).
2. PACKAGING_EXAMPLE.md — the copy-paste walkthrough that follows it.
3. REPOS.md — what the default branches still do.
4. The shorter corrections: RELEASE_PROCESS.md, README.md, GETTING_STARTED.md, architecture/FHS.md, style/WORKFLOW.md, style/DCH.md.

Corrections and how they were checked

Checked on a debootstrap Trixie chroot (debhelper 13.24.2, dh-virtualenv 1.2.2-1.7, lintian 2.122.0, debian-policy 4.7.2.0, Python 3.13.5) unless a row says otherwise. Bookworm versions are from deb.debian.org bookworm Packages and from the pool debs named below. shellcheck -S warning install.sh and actionlint 1.7.12 on .github/workflows/ both exited 0. Those files were not part of this diff.

After the merge, dpkg-buildpackage -us -uc -b in that chroot built wlanpi-hello_1.0.0_amd64.deb again. Lintian on that deb reports only unusual-interpreter for /opt/wlanpi-hello/bin/python.

• Compat level is declared once. The example and the packaging guide no longer tell you to add debian/compat. The level is debhelper-compat (= 13) in debian/control. With both present, dh clean on debhelper 13.24.2 exits 2: debhelper compat level specified both in debian/compat and in debian/control. A compat file at level 13 alone warns that the file is deprecated.
• Maintainer scripts. postinst creates the wlanpi group and user, then the log directory, then #DEBHELPER#. prerm is set -e, #DEBHELPER#, exit 0. deb-systemd-helper on Trixie implements enable, disable, purge, mask, unmask, is-enabled, was-enabled, debian-installed, update-state, and reenable. With DPKG_MAINTSCRIPT_PACKAGE set, start and stop exit 0 and do nothing. chown wlanpi:wlanpi before the user exists fails with invalid user. The built wlanpi-hello postinst has useradd/chown and then the generated deb-systemd-helper enable block plus deb-systemd-invoke start. The prerm has deb-systemd-invoke stop. The scripts are LF POSIX shell. A CRLF shebang fails with cannot execute: required file not found (exit 127).
• Test tools stay out of the .deb. requirements.txt is the runtime set. pytest lives in the pyproject test extra (pip install -e ".[test]"). dh-virtualenv 1.2.2 runs pip install -r requirements.txt when that file exists. A build with pytest and pytest-cov in it shipped pytest 9.1.1 and pytest-cov 7.1.0 (115 paths). The corrected wlanpi-hello_1.0.0_amd64.deb contains no pytest files. In the chroot, the test extra then pytest: 3 passed on Python 3.13.5.
• Unit files go to /usr/lib/systemd/system. A throwaway package that installed a unit through lib/systemd/system got lintian 2.122.0 aliased-location (error) on that path. The same unit under usr/lib/systemd/system cleared those tags. dh_installsystemd in the Trixie debhelper 13.24.2 script installs debian/<package>.service into /usr/lib/systemd/system. Bookworm's debhelper_13.11.4_all.deb still installs into lib/systemd/system. Bookworm lintian 2.116.3+deb12u1 has no aliased-location tag; its systemd-service-in-odd-location check matches etc/systemd/system only. The docs record that split. A .install destination is usr/lib/systemd/system/ on both suites.
• One version scheme. First-party packages: debian/source/format is 3.0 (native), changelog version major.minor.patch with no Debian revision, __version__.py (and pyproject.toml) the same major.minor.patch and the same pre-release when there is one, filename <package>_1.2.3_<arch>.deb. 3.0 (quilt) is for a separate upstream tarball, version <upstream>-<revision>. dpkg-source -b on 3.0 (native) with 1.0.0-1 errors: native package version may not have a revision. dpkg-buildpackage -b does not check source format and will still emit a _1.0.0-1_ deb, which is why the old changelog example and the old filename could disagree. Format 1.0 with 1.0.0-1 warns and still builds; lintian 2.122 reports malformed-debian-changelog-version 1.0.0-1 (for native). Lintian 2.122 has no native-package-with-dash-version tag. The example build produced wlanpi-hello_1.0.0_amd64.deb and a 3.0 (native) .dsc. dpkg --compare-versions 1.0.0-1 gt 1.0.0 is true, so a published -1 is not replaced by the same upstream version; the next native upload is a higher upstream version. The Trixie debchange man page says -i increments the upstream version on a native package. style/DCH.md now says that and points at the scheme. The deploy gate check-py-deb-pkg-versions-match compares major.minor.patch and the pre-release (a, b, or rc and its number). 1.1.0~beta3-1 matches 1.1.0b3. An epoch, a Debian revision, a ~dev snapshot, and .postN are not compared. That matches the workflow on WLAN-Pi/gh-workflows and the text merged from docs: version gate compares pre-releases #44.
• Standards-Version: 4.7.2. Trixie's debian-policy package is 4.7.2.0. The field has three components. Bookworm's debian-policy is 4.6.2.0. Bookworm's debhelper 13.11.4 Provides: debhelper-compat (= 13), dh-virtualenv is 1.2.2-1.3, and python3-venv is in Bookworm, so the control Build-Depends line is satisfiable there. The field records the policy the packaging follows.
• dir-or-file-in-opt is an error. Lintian 2.122 marks that tag an error. A path-test package reported it for /opt; debian/<package>.lintian-overrides with a justification comment and the tag (no path) cleared every instance. dir-or-file-in-etc-opt is a separate error. After --no-compile and removing __pycache__, pip, setuptools, and wheel, the example deb's remaining lintian finding was unusual-interpreter on /opt/wlanpi-hello/bin/python, which the docs call expected for a dh_virtualenv console script. dh_lintian installs the overrides file; the guide says to leave that helper in place.
• ~gha is the Actions artifact name. In WLAN-Pi/gh-workflows sbuild-pkg.yml and sbuild-deploy-pkg.yml, actions/upload-artifact name: is ${pkg}_${version}~gha${date}+${arch}_${distro} with date -u +'%Y%m%dt%H%M%S'. package_cloud push uploads steps.build-debian-package.outputs.deb-package, the changelog version. RELEASE_PROCESS.md says that.
• The install one-liner stays on HTTPS, with the short alias beside it. README and Getting Started keep the raw GitHub URL (https://raw.githubusercontent.com/WLAN-Pi/developers/main/install.sh, which returns 200) piped to sudo bash. Both pages also show curl -fSL http://wlanpi.us/install | sudo bash. A GET of http://wlanpi.us/install to Hover's forwarder at 216.40.34.41 returns 302 to https://raw.githubusercontent.com/wlan-pi/developers/main/install.sh. A HEAD to that forwarder is 404; the GET is the request that works. Port 443 on wlanpi.us does not answer, because Hover forwarding is HTTP-only. The raw GitHub URL stays the primary one-liner because the short link's first hop is plain HTTP. The docs say the one-liner can move to https://wlanpi.us/install once the domain serves HTTPS, for example with Cloudflare redirect rules or GitHub Pages.
• REPOS.md matches the default branches, and the CI bullets are policy plus the exceptions. Kernel default branch is 7.3-trixie (gh api repos/WLAN-Pi/wlanpi-kernel). debian/compat is still on nine active repos (bridge 10, ctx 11, grafana 10, librespeed-cli 12, profiler 11, server 10, webui 12, wconsole 10, wipry 10); archived wlanpi-chat-bot is compat 12. pi-gen-bookworm (default bookworm) has build.yml and lint.yml only: Gamesight/slack-workflow-status@master, raven-actions/actionlint@v2, no dependabot.yml, no pr-size.yml (rechecked via the contents API). Source format, missing debian/copyright, Standards-Version, /lib/systemd in wlanpi-core, and inline versus reusable build/deploy workflows are listed as deviations. The target is debian/copyright, debian/source/format, #DEBHELPER# in maintainer scripts you write, LF scripts, and the shared sbuild-pkg / sbuild-deploy-pkg workflows.

  

---

Note

Low Risk
Documentation-only updates to packaging, release, and repo reference guides; no runtime or deployment code changes.

^{Reviewed by Cursor Bugbot for commit 70ecf73. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Approved. Cursor Bugbot completed successfully and left no findings that need human review. No approval policy or existing review state requires further attention.

  

_{Sent by Cursor Approval Agent: Pull Request Router and Approver}