From 4d524320b5321616a0195802ecda34c573c13352 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Thomas=20G=C3=B6ttgens?= Date: Fri, 14 Aug 2026 09:09:03 +0000 Subject: [PATCH] Add agent guideline: documentation belongs in the docs repo (#11492) Mirrored in AGENTS.md, .github/copilot-instructions.md and CLAUDE.md, with a matching CodeRabbit path instruction for **/*.md. --- .coderabbit.yaml | 13 +++++++++++++ .github/copilot-instructions.md | 1 + AGENTS.md | 1 + CLAUDE.md | 4 ++++ 4 files changed, 19 insertions(+) diff --git a/.coderabbit.yaml b/.coderabbit.yaml index a193662cb..cdcd43f3a 100644 --- a/.coderabbit.yaml +++ b/.coderabbit.yaml @@ -31,3 +31,16 @@ reviews: instructions: > meshtasticd configuration files. Bundled with meshtasticd Linux/MacOS packaging. Ensure configurations include metadata found in other configs. + - path: "**/*.md" + instructions: > + Documentation does not live in this repo; it lives in + https://github.com/meshtastic/meshtastic. Flag any NEW .md file that documents a + feature, configuration surface, API, wire format, or design, and ask for it to be + opened against the docs repo instead. Flag any attempt to recreate a docs/ + directory: it was deleted in #11488 and must not come back. Flag write-ups left in + the tree - investigation notes, mitigation plans, migration checklists, "how we got + here" narrative, summaries of what a change did - that content belongs in the PR + description and commit message. Documentation that does belong upstream must read + as a technical manual, not a novel: what it does, the settings in user terms, the + API or protocol a client speaks. No debugging journey, no rationale essays, no + changelog prose. diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index d8c5fed32..3d20ca974 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -338,6 +338,7 @@ firmware/ - Use `assert()` for invariants that should never fail - C++17 features are available (`std::optional`, structured bindings, `if constexpr`, etc.) - **Keep code comments minimal - one or two lines, max.** Comment only when the _why_ isn't obvious from the code; never restate what the next line does. No multi-paragraph block comments explaining straightforward changes. The diff and commit message carry the rationale; the code carries the behavior. +- **Documentation does not live in this repo. Do not add it here.** This repository holds firmware code. There is no `docs/` directory - the design documents that used to sit there were published to [meshtastic/meshtastic](https://github.com/meshtastic/meshtastic) in #11488 and the directory was deleted - and it must not come back. Do not create a `.md` file to describe a feature, a configuration surface, an API, a wire format, or a design; write it in the docs repo and link that PR instead. Never leave a write-up behind in the tree: no investigation notes, no mitigation plans, no migration checklists, no "how we got here" narrative, no summaries of what a change did. That is what the PR description and the commit message are for, and they are the only place it belongs. When you do write documentation upstream, write a technical manual, not a novel - what the feature does, the settings it exposes in the user's terms, and the exact API or protocol a client speaks. No story of the debugging journey, no rationale essays, no changelog prose. Concise and factual, as short as the facts allow. - **Never compare against `millis()` directly. Use `Throttle`.** `src/mesh/Throttle.h` is the sanctioned way to ask about time, and CI enforces this (`millis-deadline-check` in `.github/workflows/test_native.yml` fails the PR on a new `millis() >` / `< millis()` comparison). - `Throttle::isWithinTimespanMs(lastMs, intervalMs)` - true while still inside the cooldown. - `Throttle::hasElapsed(lastMs, intervalMs)` - its complement, true once the interval has passed (inclusive `>=`). Prefer this to spelling `!isWithinTimespanMs(...)`. diff --git a/AGENTS.md b/AGENTS.md index 5c67d124d..66a8ca684 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -81,6 +81,7 @@ Key rotation to never trigger casually: only the **full** factory reset (`factor - **Never edit or commit files under `src/mesh/generated/`.** They are regenerated from the [`meshtastic/protobufs`](https://github.com/meshtastic/protobufs) repo by the `update_protobufs.yml` workflow (entry point: `bin/regen-protos.sh`). Local edits will be overwritten and create merge conflicts. If a `.proto` change is needed, open a PR against the protobufs repo first, then let the workflow re-sync this repo. - **`confirm=True` on destructive MCP tools is a real gate, not a formality.** Don't bypass it via auto-approve settings. - **Keep code comments minimal - one or two lines, max.** Comment only when the _why_ isn't obvious from the code; never restate what the next line does. No multi-paragraph block comments explaining straightforward changes. The diff and commit message carry the rationale; the code carries the behavior. +- **Documentation does not live in this repo. Do not add it here.** This repository holds firmware code. There is no `docs/` directory - the design documents that used to sit there were published to [meshtastic/meshtastic](https://github.com/meshtastic/meshtastic) in #11488 and the directory was deleted - and it must not come back. Do not create a `.md` file to describe a feature, a configuration surface, an API, a wire format, or a design; write it in the docs repo and link that PR instead. Never leave a write-up behind in the tree: no investigation notes, no mitigation plans, no migration checklists, no "how we got here" narrative, no summaries of what a change did. That is what the PR description and the commit message are for, and they are the only place it belongs. When you do write documentation upstream, write a technical manual, not a novel - what the feature does, the settings it exposes in the user's terms, and the exact API or protocol a client speaks. No story of the debugging journey, no rationale essays, no changelog prose. Concise and factual, as short as the facts allow. - **Never compare against `millis()` directly. Use `Throttle`.** `src/mesh/Throttle.h` is the sanctioned way to ask about time, and CI enforces this (`millis-deadline-check` in `.github/workflows/test_native.yml` fails the PR on a new `millis() >` / `< millis()` comparison). - `Throttle::isWithinTimespanMs(lastMs, intervalMs)` - true while still inside the cooldown. - `Throttle::hasElapsed(lastMs, intervalMs)` - its complement, true once the interval has passed (inclusive `>=`). Prefer this to spelling `!isWithinTimespanMs(...)`. diff --git a/CLAUDE.md b/CLAUDE.md index 325fb7100..a7dbf6991 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -22,3 +22,7 @@ **Read `.github/copilot-instructions.md` first.** That file is the canonical agent-facing document for this repo. It covers project layout, coding conventions, the build system, CI/CD, the native C++ test suite, and the MCP Server & Hardware Test Harness. Read it top-to-bottom before starting any non-trivial change. This file (`CLAUDE.md`) is a short pointer for Claude Code sessions. Slash commands live in `.claude/commands/`. + +## House rule: documentation does not live in this repo + +This repository holds firmware code. There is no `docs/` directory - the design documents that used to sit there were published to [meshtastic/meshtastic](https://github.com/meshtastic/meshtastic) in #11488 and the directory was deleted - and it must not come back. Do not create a `.md` file to describe a feature, a configuration surface, an API, a wire format, or a design; write it in the docs repo and link that PR instead. Never leave a write-up behind in the tree: no investigation notes, no mitigation plans, no migration checklists, no "how we got here" narrative, no summaries of what a change did. That is what the PR description and the commit message are for, and they are the only place it belongs. When you do write documentation upstream, write a technical manual, not a novel - what the feature does, the settings it exposes in the user's terms, and the exact API or protocol a client speaks. No story of the debugging journey, no rationale essays, no changelog prose. Concise and factual, as short as the facts allow.