From: Josh Boyer Date: Tue, 9 Jun 2026 14:58:15 +0000 (-0400) Subject: AGENTS.md, README: address second round of MR review X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=7ad9f3aaa96bb3091d891295cf808faf67bcb96d;p=linux-firmware.git AGENTS.md, README: address second round of MR review - Golden rule #1: note license texts are a second WHENCE-accounting exception (referenced via Licence: lines, stored in LICENSES/), not just repository tooling in the known_files allowlist. - Require new license files to live in the LICENSES/ directory, in both AGENTS.md and README.md, matching the LICENSES/ layout now on main. - Encourage including a firmware changelog in the commit message, since for binary blobs the commit message is often the only human-readable record of the change. Signed-off-by: Josh Boyer Assisted-by: Claude Opus 4.8 --- diff --git a/AGENTS.md b/AGENTS.md index 635626e4..66a9a460 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -24,12 +24,18 @@ Upstream lives at . 1. **Every file in git must be accounted for** — *almost always* by a `WHENCE` entry. Adding a firmware blob without one breaks the build; removing or - renaming one without updating `WHENCE` does too. **The exception is - repository tooling/metadata** (this file, `README.md`, `check_whence.py`, - etc.), which is registered in the `known_files` allowlist *inside* - `check_whence.py`. If `make check` reports a non-firmware file is - unaccounted for, add it to that allowlist — **never to `WHENCE`** (see - "Things to leave alone"). + renaming one without updating `WHENCE` does too. There are two kinds of + exception: + - **Repository tooling/metadata** (this file, `README.md`, + `check_whence.py`, etc.) is registered in the `known_files` allowlist + *inside* `check_whence.py`. + - **License texts** live in the `LICENSES/` directory and are accounted for + by being referenced from a `Licence:` line in `WHENCE` (e.g. + `See LICENCE.foo for details.`) — not by a `File:` entry. + + If `make check` reports a file is unaccounted for, place it in the right + bucket above. **Don't add tooling or license files to `WHENCE` as `File:` + entries** to silence a check (see "Things to leave alone"). 2. **Never invent license information.** The license and the redistributability of a blob are facts that come from the firmware's owner — usually conveyed in the submitter's commit and `Signed-off-by`. If you don't have it, don't guess. @@ -48,9 +54,11 @@ Upstream lives at . 2. Add a stanza to `WHENCE` (see "WHENCE format" below) declaring the file and its license. Group it with related entries; keep the file roughly ordered as the surrounding content is. -3. If the firmware needs a new license, add a `LICENSE.` (or - `LICENCE.` — both spellings exist) file and reference it from - `WHENCE` with `See LICENSE. for details.` +3. If the firmware needs a new license, the license text **must** go in the + `LICENSES/` directory as `LICENSES/LICENSE.` (or + `LICENSES/LICENCE.` — both spellings exist in the tree). Reference + it from `WHENCE` with `See LICENSE. for details.` using the bare + filename; `check_whence.py` resolves it under `LICENSES/`. 4. Run `make check`. 5. Commit with a `Signed-off-by` from someone authoritative on the license, and — if an agent helped produce the change — a trailer noting AI @@ -71,7 +79,9 @@ keywords that matter: - `Version:` / `Info:` — optional metadata lines. - `Licence:` / `License:` — the license terms. Either name an inline word (e.g. `Redistributable`, `GPLv2`) or refer out with - `See for details.` The referenced file must exist in the tree. + `See for details.` Referenced license files live in the + `LICENSES/` directory and are cited by bare filename (the checker resolves + the path); the file must exist there. Spaces in paths are backslash-escaped (e.g. `foo\ bar.bin`). @@ -115,6 +125,10 @@ check and it reports a phantom mismatch. authority over the firmware's licensing (typically from within the owning company). CI (`ci-fairy check-commits --signed-off-by`) rejects commits without it. Do not add one yourself — ask the user. +- **Include a firmware changelog in the commit message where possible** — what + changed in this firmware revision (fixes, new device support, version bumps). + For binary blobs the commit message is often the only human-readable record + of the change, so capture whatever the vendor provides. - If an AI agent assisted in producing the commit, record it with a trailer such as `Assisted-by: ` (an equivalent `Co-developed-by:` / `Co-Authored-By:` is fine). The exact tag isn't critical; surfacing that AI diff --git a/README.md b/README.md index 8481892c..415576dc 100644 --- a/README.md +++ b/README.md @@ -47,10 +47,15 @@ clearly state the license under which the firmware is available, and that it is redistributable. Being redistributable includes ensuring the firmware license provided includes an implicit or explicit patent grant to end users to ensure full functionality of device -operation with the firmware. If the license is long and involved, it's -permitted to include it in a separate file and refer to it from the -`WHENCE` file (IE _'See `LICENSE.foo` for details.'_). -And if it were possible, a changelog of the firmware itself. +operation with the firmware. If the license is long and involved, the +license text may be kept in a separate file rather than inline in `WHENCE`. +Any such separate license file **must** be placed in the `LICENSES/` +directory and referenced from the `WHENCE` file (IE _'See `LICENSE.foo` for +details.'_). + +Where possible, the commit message should also include a changelog of the +firmware itself — what changed in this revision — since for binary firmware +the commit message is frequently the only human-readable record of the change. To maintain consistent quality on the repository, please run the following before submitting a patch: