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 <jwboyer@kernel.org>
Assisted-by: Claude Opus 4.8 <noreply@anthropic.com>

diff --git a/AGENTS.md b/AGENTS.md
index 635626e4258a227744b3944c6572bf7d4e25e5bf..66a9a460be0141bd3d5fccc6f9a51991404b5dd7 100644 (file)
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -24,12 +24,18 @@ Upstream lives at <https://gitlab.com/kernel-firmware/linux-firmware.git>.
 
 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 <https://gitlab.com/kernel-firmware/linux-firmware.git>.
 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.<vendor>` (or
-   `LICENCE.<vendor>` — both spellings exist) file and reference it from
-   `WHENCE` with `See LICENSE.<vendor> for details.`
+3. If the firmware needs a new license, the license text **must** go in the
+   `LICENSES/` directory as `LICENSES/LICENSE.<vendor>` (or
+   `LICENSES/LICENCE.<vendor>` — both spellings exist in the tree). Reference
+   it from `WHENCE` with `See LICENSE.<vendor> 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 <LICENSE-file> for details.` The referenced file must exist in the tree.
+  `See <LICENSE-file> 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: <tool/model>` (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 8481892cd1b2b8762894f8b9058a41abd2927060..415576dc5a0e07bd90f53c770aff2870a6ff8a22 100644 (file)
--- 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: