From 7e8e4d2c812bdec65330865bdc07c257dee450f8 Mon Sep 17 00:00:00 2001 From: jsz Date: Sat, 24 Oct 2026 03:27:50 +0000 Subject: [PATCH 1/4] docs: add org-wide agent guidance Root AGENTS.md stays local to this repo. The org file links the existing docs and states the Trixie and Python 3.13 rule. --- AGENTS.md | 3 ++ GETTING_STARTED.md | 2 +- README.md | 1 + agents/AGENTS.md | 83 ++++++++++++++++++++++++++++++++++++++++++++++ style/PYTHON.md | 14 ++++++-- 5 files changed, 99 insertions(+), 4 deletions(-) create mode 100644 agents/AGENTS.md diff --git a/AGENTS.md b/AGENTS.md index 995288a..97fe5c8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,5 +1,8 @@ # Guidance for coding agents +This file is local guidance for editing the `developers` repository. +Org-wide guidance for any WLAN Pi repo is in [agents/AGENTS.md](agents/AGENTS.md). + This repository is documentation only. There is no application code here. ## Ground rules diff --git a/GETTING_STARTED.md b/GETTING_STARTED.md index 3cd16e7..5cb0638 100644 --- a/GETTING_STARTED.md +++ b/GETTING_STARTED.md @@ -109,7 +109,7 @@ Best for: Application development, testing without hardware You can develop on any Linux system with: -- Python 3.13+ +- Python 3.13 - Git - Standard build tools (`build-essential`, `debhelper`) diff --git a/README.md b/README.md index 5afeb86..f8c685d 100644 --- a/README.md +++ b/README.md @@ -37,6 +37,7 @@ serves HTTPS, for example with Cloudflare redirect rules or GitHub Pages. | [Git Workflow Guide](GIT_WORKFLOW.md) | Git fundamentals for beginners | | [Contributing](CONTRIBUTING.md) | Detailed Git workflow, branch naming, PR guidelines, and code review | | [Packaging Example](PACKAGING_EXAMPLE.md) | Complete walkthrough of creating a Debian package from scratch | +| [Agent Guidance](agents/AGENTS.md) | Org-wide guidance for agents working in any WLAN Pi repo | ### For Core Team diff --git a/agents/AGENTS.md b/agents/AGENTS.md new file mode 100644 index 0000000..310fbdc --- /dev/null +++ b/agents/AGENTS.md @@ -0,0 +1,83 @@ +# Agent Guidance + +Org-wide guidance for an agent working in any WLAN Pi repository. The linked +documents are the source of truth. This file is a first cut maintainers can +extend. It is not an exhaustive standard, and it does not replace human review. + +A per-repo stub, when one exists, should link here and add no rules of its own. + +## Authority + +The [developers](https://github.com/WLAN-Pi/developers) repository is the +source of truth for how WLAN Pi software is built. + +A README or an older branch shows what that repo did. It does not override +this repository. Archived repos, legacy repos, and older Debian suite branches +never override the current guidance here. + +## Platform + +Current development targets Debian 13 Trixie and Python 3.13. That is the +system `python3` package in Trixie. The version is 3.13, not "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}`. + +Python 3.11 on Bookworm and Python 3.9 on Bullseye are valid only when the +work is on that suite branch, or is a fix to an existing package. See +[Python version guidelines](https://github.com/WLAN-Pi/developers/blob/main/style/PYTHON.md#python-version-guidelines). + +When the target suite or Python version changes, update this section and +`style/PYTHON.md` in the same change. + +## How to work + +- Be concise. Skip filler. +- Do not use an em dash. Do not use `--` as punctuation. `--` belongs only in a CLI flag or a URL. +- When the task is ambiguous, ask. Do not guess. +- Build only what was asked. Do not add files, abstractions, dependencies, or features that were not requested. +- Use the least code that solves the problem. After it works, do a second pass that simplifies and deletes unused code. +- Before you hand work off, review your own output. Read the change as a critic against the request, the platform rule above, and the linked docs. Fix what that review finds, then hand it off. +- Prefer boring, well-understood tools. If you reach for something novel, say why. +- Match the style of the file you are editing. +- Keep each pull request small enough to review. The size policy is in [PR Size and Scope](https://github.com/WLAN-Pi/developers/blob/main/CONTRIBUTING.md#pr-size-and-scope). + +## Python + +Follow [style/PYTHON.md](https://github.com/WLAN-Pi/developers/blob/main/style/PYTHON.md). + +For a new package, use `pyproject.toml`, not `setup.py`. The app should run as `python -m app`. Parse arguments with `argparse`. Test with `pytest`. Use `tox` for test, lint, and format. + +## Packaging + +WLAN Pi ships Debian `.deb` packages. Follow [Packaging](https://github.com/WLAN-Pi/developers/blob/main/architecture/PACKAGING.md) and [FHS](https://github.com/WLAN-Pi/developers/blob/main/architecture/FHS.md). + +Package names use the `wlanpi-` prefix. Set `debhelper-compat (= 13)`. Python apps use `dh_virtualenv` where that is how the app is installed. App files go under `/opt/wlanpi-{app}`, config under `/etc/wlanpi-{app}`, logs under `/var/log/wlanpi-{app}`, and variable data under `/var/lib/wlanpi-{app}`. Install systemd units where [FHS](https://github.com/WLAN-Pi/developers/blob/main/architecture/FHS.md#shared-system-paths) says to put them. + +## Documentation + +Follow [README Standards](https://github.com/WLAN-Pi/developers/blob/main/style/README_STANDARDS.md). + +Use Markdown, not reStructuredText. Open with a short What / Why section. Use Title Case headings and a language hint on every fenced code block. Keep the tone neutral. Link back to the developers repository. + +## Git and releases + +Follow [Contributing](https://github.com/WLAN-Pi/developers/blob/main/CONTRIBUTING.md), [Git Workflow](https://github.com/WLAN-Pi/developers/blob/main/GIT_WORKFLOW.md), [Release Process](https://github.com/WLAN-Pi/developers/blob/main/RELEASE_PROCESS.md), and [debchange](https://github.com/WLAN-Pi/developers/blob/main/style/DCH.md). + +`main` is the long-lived development branch. Open pull requests against it. Do not commit directly to `main`. Manage `debian/changelog` with `dch`. + +## Licensing + +Prefer BSD-3-Clause for a new project. Follow the [Licensing Guide](https://github.com/WLAN-Pi/developers/blob/main/licensing/licensing.md). + +## Recognizing Cruft + +Do not copy the patterns below. They appear in old repos and old docs. They are not the current target. This list names patterns, not repositories. + +- 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 current development target. +- `setup.py` for a new package. +- A pattern taken from an archived, abandoned, or legacy repo. + +When a local file and this guidance disagree, follow this file. diff --git a/style/PYTHON.md b/style/PYTHON.md index c6487b9..0880b64 100644 --- a/style/PYTHON.md +++ b/style/PYTHON.md @@ -32,11 +32,19 @@ When using abbreviations with `CamelCase`, capitalize all the letters of the abb ## Python version guidelines -[Python 3.13](https://docs.python.org/3.13/) is the standard for new development. This aligns with the system Python in Debian Trixie, which is the active development target for WLAN Pi. +WLAN Pi follows Debian Trixie's system `python3` package. That version is +[Python 3.13](https://docs.python.org/3.13/). Do not target Python 3.14 or +3.15. Do not describe this policy as `3.13+`. Do not select a production +interpreter with pyenv, conda, or uv. -Bookworm (Python 3.11) may still receive bug fixes on existing packages. Bullseye (Python 3.9) is end-of-life for WLAN Pi. +Python 3.11 on Bookworm and Python 3.9 on Bullseye are valid only on that +suite branch, or when fixing an existing package. -Existing repos may still carry older targets such as `py39` or `py311` in their `tox.ini` and `pyproject.toml`. These should be updated to include `py313` when the repo is next actively worked on. +Existing repos may still carry `py39` or `py311` in `tox.ini` or +`pyproject.toml`. Include `py313` when the repo is next actively worked on. + +When this policy changes, update this section and +[agents/AGENTS.md](../agents/AGENTS.md) in the same change. ## Tests From c3cc8a147177c2d27240ee075280ccf065b5306a Mon Sep 17 00:00:00 2001 From: jsz Date: Sat, 24 Oct 2026 23:16:07 -0400 Subject: [PATCH 2/4] Merge main into agent guidance --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index f8c685d..8f34c52 100644 --- a/README.md +++ b/README.md @@ -37,6 +37,7 @@ serves HTTPS, for example with Cloudflare redirect rules or GitHub Pages. | [Git Workflow Guide](GIT_WORKFLOW.md) | Git fundamentals for beginners | | [Contributing](CONTRIBUTING.md) | Detailed Git workflow, branch naming, PR guidelines, and code review | | [Packaging Example](PACKAGING_EXAMPLE.md) | Complete walkthrough of creating a Debian package from scratch | +| [Land a Fix and Cut a Release](RELEASING.md) | Fix branches leave the version alone. The release pull request sets it | | [Agent Guidance](agents/AGENTS.md) | Org-wide guidance for agents working in any WLAN Pi repo | ### For Core Team From acf0f874358595a5597ba0e6fc10656af9f35ab4 Mon Sep 17 00:00:00 2001 From: jsz Date: Sat, 24 Oct 2026 23:16:07 -0400 Subject: [PATCH 3/4] docs: add release and versioning rules to agent guidance --- agents/AGENTS.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/agents/AGENTS.md b/agents/AGENTS.md index 310fbdc..dde3799 100644 --- a/agents/AGENTS.md +++ b/agents/AGENTS.md @@ -54,6 +54,8 @@ WLAN Pi ships Debian `.deb` packages. Follow [Packaging](https://github.com/WLAN Package names use the `wlanpi-` prefix. Set `debhelper-compat (= 13)`. Python apps use `dh_virtualenv` where that is how the app is installed. App files go under `/opt/wlanpi-{app}`, config under `/etc/wlanpi-{app}`, logs under `/var/log/wlanpi-{app}`, and variable data under `/var/lib/wlanpi-{app}`. Install systemd units where [FHS](https://github.com/WLAN-Pi/developers/blob/main/architecture/FHS.md#shared-system-paths) says to put them. +Set `debian/source/format` to `3.0 (native)`. A version has no Debian revision, and `__version__.py`, `debian/changelog`, and the git tag carry the same version. See [Source Format and Version](https://github.com/WLAN-Pi/developers/blob/main/architecture/PACKAGING.md#source-format-and-version). + ## Documentation Follow [README Standards](https://github.com/WLAN-Pi/developers/blob/main/style/README_STANDARDS.md). @@ -62,9 +64,14 @@ Use Markdown, not reStructuredText. Open with a short What / Why section. Use Ti ## Git and releases -Follow [Contributing](https://github.com/WLAN-Pi/developers/blob/main/CONTRIBUTING.md), [Git Workflow](https://github.com/WLAN-Pi/developers/blob/main/GIT_WORKFLOW.md), [Release Process](https://github.com/WLAN-Pi/developers/blob/main/RELEASE_PROCESS.md), and [debchange](https://github.com/WLAN-Pi/developers/blob/main/style/DCH.md). +Follow [Contributing](https://github.com/WLAN-Pi/developers/blob/main/CONTRIBUTING.md), [Git Workflow](https://github.com/WLAN-Pi/developers/blob/main/GIT_WORKFLOW.md), [Land a Fix and Cut a Release](https://github.com/WLAN-Pi/developers/blob/main/RELEASING.md), [Release Process](https://github.com/WLAN-Pi/developers/blob/main/RELEASE_PROCESS.md), and [debchange](https://github.com/WLAN-Pi/developers/blob/main/style/DCH.md). + +`main` is the long-lived development branch. Open pull requests against it. Do not commit directly to `main`. When `main` moves, merge `main` into your branch. Do not rebase or force-push a shared branch. -`main` is the long-lived development branch. Open pull requests against it. Do not commit directly to `main`. Manage `debian/changelog` with `dch`. +- A fix or feature pull request does not change the version, `__version__.py`, or `debian/changelog`. +- A separate release pull request sets the version and writes the changelog with `dch`. +- Before you call a version released, check both [wlanpi/dev](https://packagecloud.io/wlanpi/dev) and [wlanpi/main](https://packagecloud.io/wlanpi/main). +- pi-gen and the kernel follow their own release rules. See the Scope section of [Land a Fix and Cut a Release](https://github.com/WLAN-Pi/developers/blob/main/RELEASING.md#scope). ## Licensing @@ -78,6 +85,8 @@ Do not copy the patterns below. They appear in old repos and old docs. They are - A hardcoded `python3.9` or `python3.11` path on work that targets Trixie. - Bookworm, Bullseye, or Buster described as the current development target. - `setup.py` for a new package. +- A Debian revision such as `-1` on a new version. +- A version or changelog bump inside a fix pull request. - A pattern taken from an archived, abandoned, or legacy repo. When a local file and this guidance disagree, follow this file. From 97684a013c9ef5346c53d898f9e80f53a54ce540 Mon Sep 17 00:00:00 2001 From: jsz Date: Mon, 26 Oct 2026 03:06:41 +0000 Subject: [PATCH 4/4] docs: state standards, not a repo census New work targets Python 3.13. Old suite branches are only for a hotfix. Release text matches what is live: dev upload now, main upload and auto-tag later. --- AGENTS.md | 23 ++++++----- README.md | 6 ++- RELEASING.md | 4 +- agents/AGENTS.md | 82 +++++++++++++++++++++++++++------------ architecture/PACKAGING.md | 7 ++-- style/PYTHON.md | 16 +++++--- 6 files changed, 94 insertions(+), 44 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 97fe5c8..6e37731 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,5 +1,11 @@ # Guidance for coding agents +This repository states the standard for WLAN Pi work: how and why a thing is +done, and what the result should be. It is not an inventory of what each +repository currently is. When a repository differs, that is drift to fix in +that repository, or a deliberate change to the standard here. It is not a +documentation error. + This file is local guidance for editing the `developers` repository. Org-wide guidance for any WLAN Pi repo is in [agents/AGENTS.md](agents/AGENTS.md). @@ -9,9 +15,9 @@ This repository is documentation only. There is no application code here. - Do not invent behavior. Verify every technical claim against the actual repository before writing it. If you cannot verify it, say so or omit it. -- Distinguish the target from the current state. Mark aspirational rules as - goals. [REPOS.md](REPOS.md) is the stable map of each repo's default branch, - package, and build and release workflows. +- Write the standard, not a census of what repos do today. A difference in + another repo is drift to fix there, or a deliberate change to the standard + in this repo. - Keep docs as the single source of truth. Do not duplicate the same guidance across files; link instead. - Prefer editing an existing file over adding a new one. @@ -46,10 +52,9 @@ This repository is documentation only. There is no application code here. ## Keeping REPOS.md current -`REPOS.md` is a stable map of the other repositories: default branch, package -name, and how each one builds and releases. When a repo changes its default -branch, package name, or build and release workflows, update the matching row. +`REPOS.md` says what each repository should be. When the standard for a +repository changes, update the matching row. -Do not record changelog versions, release tags, Dependabot status, or per-repo -gaps in `REPOS.md`. Current versions live in each repo's `debian/changelog` -and on its GitHub Releases page. +Do not record changelog versions, which jobs a repo calls today, Dependabot +status, or per-repo gaps. Current versions live in each repo's +`debian/changelog` and on its GitHub Releases page. diff --git a/README.md b/README.md index 8f34c52..93ed1e4 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,10 @@ # Developers -A collection of documentation for WLAN Pi developers and contributors. +This repository states the standard for WLAN Pi work: how and why a thing is +done, and what the result should be. It is not an inventory of what each +repository currently is. When a repository differs, that is drift to fix in +that repository, or a deliberate change to the standard here. It is not a +documentation error. ## Quick Start diff --git a/RELEASING.md b/RELEASING.md index 41c60d9..a2df300 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -18,7 +18,9 @@ Planned, and not live yet: ## Scope -This page covers first-party packages that use `debian/changelog`. A repackaged third-party package that uses `3.0 (quilt)` keeps its Debian revision. See [Source Format and Version](architecture/PACKAGING.md#source-format-and-version). +This page covers first-party packages that use `debian/changelog`. See [Source Format and Version](architecture/PACKAGING.md#source-format-and-version). + +A forked upstream project versions as `+wlanpi`, for example `2.3.0+wlanpi1`. The suffix marks our rebuild of that upstream version, so we do not take the number upstream will publish next. **pi-gen** and the **kernel** follow their own rules. They are out of scope. diff --git a/agents/AGENTS.md b/agents/AGENTS.md index dde3799..6869456 100644 --- a/agents/AGENTS.md +++ b/agents/AGENTS.md @@ -1,10 +1,19 @@ # Agent Guidance -Org-wide guidance for an agent working in any WLAN Pi repository. The linked -documents are the source of truth. This file is a first cut maintainers can -extend. It is not an exhaustive standard, and it does not replace human review. +This repository states the standard for WLAN Pi work: how and why a thing is +done, and what the result should be. It is not an inventory of what each +repository currently is. When a repository differs, that is drift to fix in +that repository, or a deliberate change to the standard here. It is not a +documentation error. -A per-repo stub, when one exists, should link here and add no rules of its own. +The linked documents are the source of truth for their topics. This file does +not replace human review. + +Org standards win on a cross-cutting rule: platform, packaging, versioning, +CI, and issues. A repository's own `AGENTS.md` may add build, release, or test +rules that apply only in that repository. `pi-gen`, `wlanpi-kernel`, and +`wlanpi-core` are examples. If a local rule conflicts with a cross-cutting +standard, raise the conflict. Do not silently follow either side. ## Authority @@ -12,19 +21,22 @@ The [developers](https://github.com/WLAN-Pi/developers) repository is the source of truth for how WLAN Pi software is built. A README or an older branch shows what that repo did. It does not override -this repository. Archived repos, legacy repos, and older Debian suite branches -never override the current guidance here. +this repository. Archived repos and legacy repos never override the current +guidance here. ## Platform -Current development targets Debian 13 Trixie and Python 3.13. That is the -system `python3` package in Trixie. The version is 3.13, not "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}`. - -Python 3.11 on Bookworm and Python 3.9 on Bullseye are valid only when the -work is on that suite branch, or is a fix to an existing package. See +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 +`debian/bullseye` exist only for a hotfix to an old release. That hotfix uses +the suite branch and that suite's Python. New work never targets those +branches. See [Python version guidelines](https://github.com/WLAN-Pi/developers/blob/main/style/PYTHON.md#python-version-guidelines). When the target suite or Python version changes, update this section and @@ -46,7 +58,7 @@ When the target suite or Python version changes, update this section and Follow [style/PYTHON.md](https://github.com/WLAN-Pi/developers/blob/main/style/PYTHON.md). -For a new package, use `pyproject.toml`, not `setup.py`. The app should run as `python -m app`. Parse arguments with `argparse`. Test with `pytest`. Use `tox` for test, lint, and format. +For a new package, use `pyproject.toml`, not `setup.py`. Declare `requires-python = ">=3.13"` and plan and test on 3.13. The app should run as `python -m app`. Parse arguments with `argparse`. Test with `pytest`. Use `tox` for test, lint, and format. ## Packaging @@ -54,7 +66,13 @@ WLAN Pi ships Debian `.deb` packages. Follow [Packaging](https://github.com/WLAN Package names use the `wlanpi-` prefix. Set `debhelper-compat (= 13)`. Python apps use `dh_virtualenv` where that is how the app is installed. App files go under `/opt/wlanpi-{app}`, config under `/etc/wlanpi-{app}`, logs under `/var/log/wlanpi-{app}`, and variable data under `/var/lib/wlanpi-{app}`. Install systemd units where [FHS](https://github.com/WLAN-Pi/developers/blob/main/architecture/FHS.md#shared-system-paths) says to put them. -Set `debian/source/format` to `3.0 (native)`. A version has no Debian revision, and `__version__.py`, `debian/changelog`, and the git tag carry the same version. See [Source Format and Version](https://github.com/WLAN-Pi/developers/blob/main/architecture/PACKAGING.md#source-format-and-version). +Set `debian/source/format` to `3.0 (native)` for a first-party package. A version has no Debian revision. `__version__.py` and `debian/changelog` carry the same version. See [Source Format and Version](https://github.com/WLAN-Pi/developers/blob/main/architecture/PACKAGING.md#source-format-and-version). + +A forked upstream project versions as `+wlanpi`, for example `2.3.0+wlanpi1`. The suffix marks our rebuild of that upstream version, so we do not take the number upstream will publish next. See [Scope](https://github.com/WLAN-Pi/developers/blob/main/RELEASING.md#scope). + +## 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. ## Documentation @@ -68,10 +86,28 @@ Follow [Contributing](https://github.com/WLAN-Pi/developers/blob/main/CONTRIBUTI `main` is the long-lived development branch. Open pull requests against it. Do not commit directly to `main`. When `main` moves, merge `main` into your branch. Do not rebase or force-push a shared branch. +What is live today is [What Is Live](https://github.com/WLAN-Pi/developers/blob/main/RELEASING.md#what-is-live): + - A fix or feature pull request does not change the version, `__version__.py`, or `debian/changelog`. -- A separate release pull request sets the version and writes the changelog with `dch`. -- Before you call a version released, check both [wlanpi/dev](https://packagecloud.io/wlanpi/dev) and [wlanpi/main](https://packagecloud.io/wlanpi/main). -- pi-gen and the kernel follow their own release rules. See the Scope section of [Land a Fix and Cut a Release](https://github.com/WLAN-Pi/developers/blob/main/RELEASING.md#scope). +- A release pull request sets the version and writes the changelog with `dch`. +- A `debian/changelog` push to `main` uploads to [wlanpi/dev](https://packagecloud.io/wlanpi/dev). +- Promotion to [wlanpi/main](https://packagecloud.io/wlanpi/main) is done by hand. Check both repos before you call a version released. +- An upload to `wlanpi/main` when the release pull request merges, and an automatic tag, are planned. They are not live. Do not describe them as current behavior. + +pi-gen and the kernel follow their own release rules. See [Scope](https://github.com/WLAN-Pi/developers/blob/main/RELEASING.md#scope). + +## Images + +These are standards for image contents, not a reading of a current build. + +- WLAN Pi Go is BE200-only. Ship only BE200 firmware: every `iwlwifi-gl-c0-fm-c0-*` ucode file, plus `pnvm`. Other device firmware does not match that radio. +- The Go image must not ship `wpa_supplicant` and must not run it. That supplicant is not part of the Go. +- A person using the Go must be able to set the regulatory domain. +- `wlanpi-desktop` is optional. Install it with apt when it is wanted. Do not preinstall it in the full image. + +## Issues + +An issue states the problem, the evidence, the impact, outcome-based done-when criteria, and the constraints. Put any approach in a Notes section. Notes are not binding. An agent briefed from an issue weighs alternatives. It does not treat Notes as the required design. ## Licensing @@ -83,10 +119,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 current development target. +- 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 version. +- A Debian revision such as `-1` on a new first-party version. - A version or changelog bump inside a fix pull request. -- A pattern taken from an archived, abandoned, or legacy repo. - -When a local file and this guidance disagree, follow this file. +- A pattern taken from an archived or legacy repo. diff --git a/architecture/PACKAGING.md b/architecture/PACKAGING.md index 81cca77..739073d 100644 --- a/architecture/PACKAGING.md +++ b/architecture/PACKAGING.md @@ -89,12 +89,13 @@ Do not drop `-N` from a version that is already published. `1.2.3-1` sorts higher than `1.2.3`, so the next native upload has to be a higher upstream version, for example `1.2.4`. -`3.0 (quilt)` is for a separate upstream tarball, such as a repackaged -third-party tool. The changelog version is `-` (for -example `1.0.14-1wlanpi1`), and `dpkg-source` requires +`3.0 (quilt)` is for a separate upstream tarball. `dpkg-source` requires `../_.orig.tar.*`. A quilt version with no revision fails with `no upstream tarball found`. +A forked upstream project versions as `+wlanpi`, for example +`2.3.0+wlanpi1`. See [Scope](../RELEASING.md#scope). + ## Runtime and Test Dependencies `dh_virtualenv` runs `pip install -r requirements.txt` when that file exists diff --git a/style/PYTHON.md b/style/PYTHON.md index 0880b64..0fad007 100644 --- a/style/PYTHON.md +++ b/style/PYTHON.md @@ -32,16 +32,20 @@ When using abbreviations with `CamelCase`, capitalize all the letters of the abb ## Python version guidelines -WLAN Pi follows Debian Trixie's system `python3` package. That version is -[Python 3.13](https://docs.python.org/3.13/). Do not target Python 3.14 or -3.15. Do not describe this policy as `3.13+`. Do not select a production +Plan and test on [Python 3.13](https://docs.python.org/3.13/), the system +`python3` in Debian 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. -Python 3.11 on Bookworm and Python 3.9 on Bullseye are valid only on that -suite branch, or when fixing an existing package. +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 +`debian/bullseye` exist only for a hotfix to an old release. That hotfix uses +the suite branch and that suite's Python. New work never targets those +branches. Existing repos may still carry `py39` or `py311` in `tox.ini` or -`pyproject.toml`. Include `py313` when the repo is next actively worked on. +`pyproject.toml`. Include `py313` when the repo is next actively worked on, +unless the change is a hotfix on that old suite branch. When this policy changes, update this section and [agents/AGENTS.md](../agents/AGENTS.md) in the same change.