From 3e947e0196da4ca6fb638c453dc32094be876e18 Mon Sep 17 00:00:00 2001 From: jsz Date: Tue, 27 Oct 2026 01:15:37 +0000 Subject: [PATCH 1/2] docs: keep the Debian suite configurable with a trixie default Clarify that Trixie is what we ship and what CI on main builds, while build scripts and workflows take the suite as a parameter defaulting to Trixie. Positive wording only; avoids misreading trixie-only as hardcoding. --- CONTRIBUTING.md | 11 ++++++++--- GETTING_STARTED.md | 7 +++++++ PACKAGING_EXAMPLE.md | 6 +++--- RELEASE_PROCESS.md | 8 +++----- agents/AGENTS.md | 23 ++++++++++++++++------- architecture/PACKAGING.md | 8 +++++--- 6 files changed, 42 insertions(+), 21 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8835923..e14b831 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -25,9 +25,14 @@ This guide covers how to contribute code to WLAN Pi projects. For setting up you branches from `main`, and open pull requests against `main`. The exception is `wlanpi-kernel`, which keeps one branch per kernel version. -**Debian suite branches** (`debian/`, e.g. `debian/bullseye`): -- Maintained by the core team only. These preserve support for older Debian releases and are not targets for regular contributor PRs. -- Build matrices on these branches are scoped to their specific suite only. +**Debian target on `main`:** WLAN Pi ships packages built for Debian Trixie. +CI runs Trixie packaging jobs. Build scripts, Dockerfiles, and shared +workflows keep the suite configurable, with Trixie as the default. See +[Agent Guidance](agents/AGENTS.md#platform). + +**Debian suite branches** (`debian/`): Maintained by the core team +only. Each branch preserves one older suite; its CI builds for that suite. +These branches are not targets for regular contributor pull requests. See [Repository Reference](REPOS.md) for each repo's default branch. diff --git a/GETTING_STARTED.md b/GETTING_STARTED.md index 5cb0638..aa2c66d 100644 --- a/GETTING_STARTED.md +++ b/GETTING_STARTED.md @@ -13,6 +13,13 @@ WLAN Pi is a specialized platform for Wi-Fi professionals. It combines custom ha This repository contains the documentation for developers who want to contribute to WLAN Pi projects. +## Debian target + +WLAN Pi ships Debian packages for Trixie. CI on `main` builds and tests those +packages. Build scripts, Dockerfiles, and workflows keep the suite +configurable, with Trixie as the default. See +[Agent Guidance](agents/AGENTS.md#platform). + ## Quick start ### 1. Install dependencies diff --git a/PACKAGING_EXAMPLE.md b/PACKAGING_EXAMPLE.md index 47b8185..598c0bd 100644 --- a/PACKAGING_EXAMPLE.md +++ b/PACKAGING_EXAMPLE.md @@ -605,9 +605,9 @@ jobs: ``` The deploy workflow fires when a `debian/changelog` change reaches `main`. A -git tag on its own does not deploy. The `sbuild-deploy-pkg` reusable workflow -builds for the Debian suites in its `distros` input and uploads to the -Packagecloud `dev` repository. +git tag on its own does not deploy. The `sbuild-deploy-pkg` reusable workflow builds for the suite or suites in +its `distros` input (Trixie by default) and uploads to the Packagecloud +`dev` repository. ## Step 9: Complete filesystem structure diff --git a/RELEASE_PROCESS.md b/RELEASE_PROCESS.md index 88ddf9a..208af6e 100644 --- a/RELEASE_PROCESS.md +++ b/RELEASE_PROCESS.md @@ -26,11 +26,9 @@ General branching strategy. May vary per repo. | `hotfix/` | Urgent fixes against `main` | | `release/` | Version bump for a release | -> `debian/` branches (e.g. `debian/bullseye`) -> are maintained by the core team. They are branched from a known-good commit -> before trixie-targeted work began. Build matrices on these branches target -> only their specific suite. Contributors should not open PRs against these -> branches. +> `debian/` branches let the core team preserve an older Debian +> suite. CI on each branch builds for that suite. Open pull requests against +> `main`, where Trixie is the shipping target and CI builds Trixie packages. ### Branch rules diff --git a/agents/AGENTS.md b/agents/AGENTS.md index 6869456..3286c29 100644 --- a/agents/AGENTS.md +++ b/agents/AGENTS.md @@ -26,11 +26,17 @@ guidance here. ## Platform -Debian 13 Trixie is the development target. Plan and test on Python 3.13, the -system `python3` in Trixie. Declare `requires-python = ">=3.13"`. Do not pin -`==3.13`. Do not target Python 3.14 or 3.15. Do not select a production -interpreter with pyenv, conda, or uv. Production apps ship as `.deb` packages -and may use `dh_virtualenv` under `/opt/wlanpi-{app}`. +Debian 13 Trixie is the development target. WLAN Pi ships `.deb` packages +built for Trixie. Plan and test on Python 3.13, the system `python3` in +Trixie. Declare `requires-python = ">=3.13"`. Do not pin `==3.13`. Do not +target Python 3.14 or 3.15. Do not select a production interpreter with +pyenv, conda, or uv. Production apps ship as `.deb` packages and may use +`dh_virtualenv` under `/opt/wlanpi-{app}`. + +Dockerfiles, build scripts, and workflow inputs keep the target Debian suite +configurable, with Trixie as the default (for example a `SUITE` build arg, +`DEBIAN_RELEASE`, or a workflow `distros` input). Adopting the next Debian +release is a default change, not a rewrite. Suite defaults are Python 3.9 on Bullseye, Python 3.11 on Bookworm, and Python 3.13 on Trixie. All new work targets 3.13. `debian/bookworm` and @@ -72,7 +78,9 @@ A forked upstream project versions as `+wlanpi`, for example `2.3.0 ## CI -CI should keep Debian Trixie packaging jobs, plus compiler builds and tests. Do not add sid, Bookworm, Ubuntu, Arch, or Fedora jobs. WLAN Pi ships Debian packages, so do not maintain an Arch `PKGBUILD` or an RPM spec to track versions. +CI on `main` builds and tests Debian Trixie packages, plus compiler builds and +unit tests. Reuse the same suite parameter in workflows and build scripts, +defaulting to Trixie. ## Documentation @@ -119,7 +127,8 @@ Do not copy the patterns below. They appear in old repos and old docs. They are - A system-wide `sudo python3 -m pip install`. - A hardcoded `python3.9` or `python3.11` path on work that targets Trixie. -- Bookworm, Bullseye, or Buster described as the target for new work. +- A `debian/` suite named as the target for new work on `main`. +- `trixie` hardcoded through build scripts with no suite parameter. - `setup.py` for a new package. - A Debian revision such as `-1` on a new first-party version. - A version or changelog bump inside a fix pull request. diff --git a/architecture/PACKAGING.md b/architecture/PACKAGING.md index 739073d..b15ee9b 100644 --- a/architecture/PACKAGING.md +++ b/architecture/PACKAGING.md @@ -142,9 +142,11 @@ The `Architecture: any` example above applies to packages that bundle native dependencies. Packages that ship only interpreted code or data use `Architecture: all`. -Trixie is the development target. Suites that are still supported keep a -`debian/` branch, including `debian/bookworm` -([branch strategy](../RELEASE_PROCESS.md#branch-strategy-quick-reference)). +Trixie is the shipping target on `main`. CI packaging jobs build for Trixie. +Dockerfiles and build scripts take the target suite as a parameter, defaulting +to Trixie. Suites that remain supported on a `debian/` branch, +including `debian/bookworm`, are described in +[branch strategy](../RELEASE_PROCESS.md#branch-strategy-quick-reference). Bookworm's debhelper 13.11.4 provides `debhelper-compat (= 13)`, and its dh-virtualenv is 1.2.2-1.3, so the build-dependencies in the control file above are satisfiable there. `Standards-Version: 4.7.2` names the policy From 1770090b2d0db1462d831a2c95a3ed236474e243 Mon Sep 17 00:00:00 2001 From: jsz Date: Tue, 27 Oct 2026 01:18:24 +0000 Subject: [PATCH 2/2] docs: single source for Debian suite default on main State the Trixie shipping and configurable-suite rule once in architecture/PACKAGING.md. Other docs link or drop the duplicate text. --- CONTRIBUTING.md | 11 +++-------- GETTING_STARTED.md | 7 ------- PACKAGING_EXAMPLE.md | 6 +++--- RELEASE_PROCESS.md | 8 +++++--- agents/AGENTS.md | 23 +++++++---------------- architecture/PACKAGING.md | 17 ++++++++++++----- 6 files changed, 30 insertions(+), 42 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e14b831..8835923 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -25,14 +25,9 @@ This guide covers how to contribute code to WLAN Pi projects. For setting up you branches from `main`, and open pull requests against `main`. The exception is `wlanpi-kernel`, which keeps one branch per kernel version. -**Debian target on `main`:** WLAN Pi ships packages built for Debian Trixie. -CI runs Trixie packaging jobs. Build scripts, Dockerfiles, and shared -workflows keep the suite configurable, with Trixie as the default. See -[Agent Guidance](agents/AGENTS.md#platform). - -**Debian suite branches** (`debian/`): Maintained by the core team -only. Each branch preserves one older suite; its CI builds for that suite. -These branches are not targets for regular contributor pull requests. +**Debian suite branches** (`debian/`, e.g. `debian/bullseye`): +- Maintained by the core team only. These preserve support for older Debian releases and are not targets for regular contributor PRs. +- Build matrices on these branches are scoped to their specific suite only. See [Repository Reference](REPOS.md) for each repo's default branch. diff --git a/GETTING_STARTED.md b/GETTING_STARTED.md index aa2c66d..5cb0638 100644 --- a/GETTING_STARTED.md +++ b/GETTING_STARTED.md @@ -13,13 +13,6 @@ WLAN Pi is a specialized platform for Wi-Fi professionals. It combines custom ha This repository contains the documentation for developers who want to contribute to WLAN Pi projects. -## Debian target - -WLAN Pi ships Debian packages for Trixie. CI on `main` builds and tests those -packages. Build scripts, Dockerfiles, and workflows keep the suite -configurable, with Trixie as the default. See -[Agent Guidance](agents/AGENTS.md#platform). - ## Quick start ### 1. Install dependencies diff --git a/PACKAGING_EXAMPLE.md b/PACKAGING_EXAMPLE.md index 598c0bd..35b7ff3 100644 --- a/PACKAGING_EXAMPLE.md +++ b/PACKAGING_EXAMPLE.md @@ -605,9 +605,9 @@ jobs: ``` The deploy workflow fires when a `debian/changelog` change reaches `main`. A -git tag on its own does not deploy. The `sbuild-deploy-pkg` reusable workflow builds for the suite or suites in -its `distros` input (Trixie by default) and uploads to the Packagecloud -`dev` repository. +git tag on its own does not deploy. The `sbuild-deploy-pkg` reusable workflow builds for the suites in its +`distros` input (default `["trixie"]`) and uploads to the Packagecloud `dev` +repository. ## Step 9: Complete filesystem structure diff --git a/RELEASE_PROCESS.md b/RELEASE_PROCESS.md index 208af6e..88ddf9a 100644 --- a/RELEASE_PROCESS.md +++ b/RELEASE_PROCESS.md @@ -26,9 +26,11 @@ General branching strategy. May vary per repo. | `hotfix/` | Urgent fixes against `main` | | `release/` | Version bump for a release | -> `debian/` branches let the core team preserve an older Debian -> suite. CI on each branch builds for that suite. Open pull requests against -> `main`, where Trixie is the shipping target and CI builds Trixie packages. +> `debian/` branches (e.g. `debian/bullseye`) +> are maintained by the core team. They are branched from a known-good commit +> before trixie-targeted work began. Build matrices on these branches target +> only their specific suite. Contributors should not open PRs against these +> branches. ### Branch rules diff --git a/agents/AGENTS.md b/agents/AGENTS.md index 3286c29..d28294e 100644 --- a/agents/AGENTS.md +++ b/agents/AGENTS.md @@ -26,17 +26,11 @@ guidance here. ## Platform -Debian 13 Trixie is the development target. WLAN Pi ships `.deb` packages -built for Trixie. Plan and test on Python 3.13, the system `python3` in -Trixie. Declare `requires-python = ">=3.13"`. Do not pin `==3.13`. Do not -target Python 3.14 or 3.15. Do not select a production interpreter with -pyenv, conda, or uv. Production apps ship as `.deb` packages and may use -`dh_virtualenv` under `/opt/wlanpi-{app}`. - -Dockerfiles, build scripts, and workflow inputs keep the target Debian suite -configurable, with Trixie as the default (for example a `SUITE` build arg, -`DEBIAN_RELEASE`, or a workflow `distros` input). Adopting the next Debian -release is a default change, not a rewrite. +Debian 13 Trixie is the development target. Plan and test on Python 3.13, the +system `python3` in Trixie. Declare `requires-python = ">=3.13"`. Do not pin +`==3.13`. Do not target Python 3.14 or 3.15. Do not select a production +interpreter with pyenv, conda, or uv. Production apps ship as `.deb` packages +and may use `dh_virtualenv` under `/opt/wlanpi-{app}`. Suite defaults are Python 3.9 on Bullseye, Python 3.11 on Bookworm, and Python 3.13 on Trixie. All new work targets 3.13. `debian/bookworm` and @@ -78,9 +72,7 @@ A forked upstream project versions as `+wlanpi`, for example `2.3.0 ## CI -CI on `main` builds and tests Debian Trixie packages, plus compiler builds and -unit tests. Reuse the same suite parameter in workflows and build scripts, -defaulting to Trixie. +Packaging CI on `main` follows [Target Debian suite](https://github.com/WLAN-Pi/developers/blob/main/architecture/PACKAGING.md#target-debian-suite), plus compiler builds and tests. ## Documentation @@ -127,8 +119,7 @@ Do not copy the patterns below. They appear in old repos and old docs. They are - A system-wide `sudo python3 -m pip install`. - A hardcoded `python3.9` or `python3.11` path on work that targets Trixie. -- A `debian/` suite named as the target for new work on `main`. -- `trixie` hardcoded through build scripts with no suite parameter. +- Bookworm, Bullseye, or Buster described as the target for new work. - `setup.py` for a new package. - A Debian revision such as `-1` on a new first-party version. - A version or changelog bump inside a fix pull request. diff --git a/architecture/PACKAGING.md b/architecture/PACKAGING.md index b15ee9b..38a0f20 100644 --- a/architecture/PACKAGING.md +++ b/architecture/PACKAGING.md @@ -20,6 +20,15 @@ If you want to create a new package for WLAN Pi: 2. Review this guide and the Packaging Example 3. Check [FHS Policy](FHS.md) for filesystem standards +## Target Debian suite + +On `main`, WLAN Pi ships `.deb` packages built for Debian Trixie. CI runs +packaging jobs for that suite. Dockerfiles, build scripts, and workflow inputs +take the target suite as a parameter, with Trixie as the default (for example +a `SUITE` build arg, `DEBIAN_RELEASE`, or a workflow `distros` input). +Adopting the next Debian release updates that default, not the layout of the +build. + ## Package structure All WLAN Pi packages must follow this structure: @@ -142,11 +151,9 @@ The `Architecture: any` example above applies to packages that bundle native dependencies. Packages that ship only interpreted code or data use `Architecture: all`. -Trixie is the shipping target on `main`. CI packaging jobs build for Trixie. -Dockerfiles and build scripts take the target suite as a parameter, defaulting -to Trixie. Suites that remain supported on a `debian/` branch, -including `debian/bookworm`, are described in -[branch strategy](../RELEASE_PROCESS.md#branch-strategy-quick-reference). +Trixie is the development target. Suites that are still supported keep a +`debian/` branch, including `debian/bookworm` +([branch strategy](../RELEASE_PROCESS.md#branch-strategy-quick-reference)). Bookworm's debhelper 13.11.4 provides `debhelper-compat (= 13)`, and its dh-virtualenv is 1.2.2-1.3, so the build-dependencies in the control file above are satisfiable there. `Standards-Version: 4.7.2` names the policy