From bc38b0f7352afbdfbee86028ec598ba920dff190 Mon Sep 17 00:00:00 2001 From: Swung0x48 Date: Thu, 15 Oct 2026 08:39:59 -0400 Subject: [PATCH] [Docs] (AGENTS.md, CLAUDE.md, CONTRIBUTING.md): add rules for commits, comments and files --- AGENTS.md | 17 +++++++++ CLAUDE.md | 1 + CONTRIBUTING.md | 98 +++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 116 insertions(+) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md create mode 100644 CONTRIBUTING.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..798c0aeb --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,17 @@ +# Notes for coding agents + +Read `CONTRIBUTING.md` before changing anything. Every rule in it applies to agents. + +@CONTRIBUTING.md + +- Before each commit: + 1. Stage exactly what you mean to commit (no `git commit -a`). + 2. Print the scope with `python3 scripts/check_text_hygiene.py scope`. + 3. Write the message as UTF-8 without a byte-order mark, to a file outside the repository. + 4. Check it with `python3 scripts/check_text_hygiene.py message `. + 5. Commit with `git commit -F ` once the check passes. +- On Windows, run `python` instead of `python3`. +- Do not copy the format of older commits. Much of the history before October 2026 breaks these rules. +- When you brief a sub-agent, give it the exact commit format and these rules, not a paraphrase. +- Keep working papers (briefs, reviews, scratch measurements, logs) outside the repository. +- Add no `Co-Authored-By` or other trailers. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..43c994c2 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..4ff47c93 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,98 @@ +# Contributing to MobileGL + +These rules keep the code and its history readable. `scripts/check_text_hygiene.py` checks the ones listed under [Checks](#checks); the rest rely on review. + +Commands below use `python3`. On Windows, run `python` instead. + +## Commit messages + +``` +[Type] (Scope): content + +- Detail 1 +- Detail 2 +``` + +- **Subject only by default.** Add `- ` detail lines only when a detail really needs to be in the commit message. Leave one blank line after the subject. A detail that wraps continues on at most two lines indented by two spaces. No paragraphs and no trailers. +- **Content** after `): ` is at most 72 characters of plain English in the imperative mood ("flush once per frame", not "flushes" or "flushed"). +- **Type** is one or more of these, comma-separated (`[Fix, Test]`): + - `Feat`: new behaviour. + - `Fix`: corrects behaviour. + - `Perf`: faster or lighter, same behaviour. + - `Refactor`: restructures code, same behaviour. + - `Test`: tests only. + - `Docs`: documentation and comments only. + - `Build`: CMake, Gradle, toolchains. + - `CI`: workflows and CI scripts. + - `Chore`: housekeeping such as headers, file moves and dead files. + - `Tools`: developer tools under `tools/` and `scripts/`. +- **Scope** is each changed path without a leading `MobileGL/`, cut to its first two parts: `MG_Backend/DirectGLES`, `MG_Test/Wire`, `scripts/ci`, `docs/Disaggregated`. + - A shorter path is used whole: `MG_Backend` for a file directly in a subsystem, `scripts` for a file directly in `scripts/`, and the file name for a file at the repository root (`CMakeLists.txt`). + - A file directly in `MobileGL/` uses `MobileGL`, and a submodule uses its path (`3rdparty/glslang`). + - List every scope the commit touches, comma-separated: `(MG_Backend/DirectGLES, MG_Test/Wire)`. + - `python3 scripts/check_text_hygiene.py scope` prints the scope for the staged changes. +- **No** planning ids (phase or decision codes such as `P13` or `ID-54`), local paths, external project names or non-English text anywhere in the message. +- **Merges** use `[Merge] (area): what the merge takes`. The scope is free text there. Write the subject yourself, since git's default merge message fails the check. The commits a merge brings in are not checked again. +- **Reverts** use `[Fix] (Scope): revert `. + +Example: + +``` +[Perf] (MG_Backend/DirectGLES): flush once per frame before the window pass +``` + +## Comments, strings and documentation + +- Code, comments, log strings and commit messages are in English. Documentation may be in Chinese or English. +- A comment states what the code does now and why, in a few lines. Rationale longer than about 15 lines belongs in a design document under `docs/`, with a one-line pointer in the code. +- In code and comments, cite a symbol, file or section, never a line number: `ARCHITECTURE.md ยง1.3`, `VulkanRenderer::BeginFrame()`. Documents may keep `file:line` citations; the documentation citation check resolves them. +- State the rule, not its history. No "previously" or "after review", and no planning ids in comments, strings, identifiers or file names. +- Plain wording, without ALL-CAPS emphasis. +- In code and comments (C, C++, GLSL, CMake, shell, Python, YAML), do not name external projects such as Mesa, Zink or gallium; describe the technique instead. Naming the driver or hardware where a behaviour was observed (llvmpipe, ANGLE, Adreno, Mali) is fine, and so are file, package and extension names that contain these words (`50_mesa.json`, `GL_MESA_*`). + +## Code + +- Format the lines you change with `.clang-format`, using clang-format 23. Install it with `pip install 'clang-format==23.1.3'`; `git clang-format ` from the same package formats only the lines changed since ``. `scripts/format_code.sh` reformats whole files, so do not use it on files you only touched. +- `.inc` files are fragments included in the middle of a `.cpp` file, inside a namespace, or are generated tables. clang-format cannot format them on their own, so the check skips them. Match the indentation of the file that includes them. +- Text files are UTF-8. +- These source files under `MobileGL/`, `scripts/` and `tools/` start with the license header: + - C, C++, `.inc`, GLSL, Java and JavaScript modules, with `//` comments; + - Python, shell, CMake modules and `CMakeLists.txt`, with `#` comments. + - Generated files and files under another license are exempt. `python3 scripts/update-source-file-header.py` adds the header. +- Keep files to about 3,000 lines and functions to about 300 lines. +- Platform-specific APIs stay behind an abstraction, never raw in logic code. +- A fix that restores intended behaviour ships unconditionally. Add a switch only for a real trade-off. +- A cache keyed on object identity uses a monotonic lifetime id, never a GL name or a pointer, because both are recycled. + +## What goes in the repository + +- Source, tests, build files and maintained documentation. +- Generated code, only together with a CI step that regenerates it and fails on any difference. +- Binary test fixtures. +- Not raw logs, and not working papers such as agent briefs, review rounds and drafts. Keep those outside the repository and commit the conclusion: a design-document change, a `DEBTS.md` entry, a measurement under `docs/Performance`. + +## Checks + +`python3 scripts/check_text_hygiene.py ci` runs what CI runs. It checks the commits on the branch's own line of history since the check was added. The base branch it compares with is `feat/disaggregated`, which you can change with `TEXT_HYGIENE_BASE_BRANCH`. + +These fail on any violation: + +- commit messages, as described above; +- a new file under `docs/Disaggregated/notes/` or a new `.log` file; +- a missing or wrong license header; +- a text file that is not UTF-8; +- an external project name in a comment; +- a `file:line` citation in code that points past the end of the file; +- changed lines that clang-format would change. + +These are ratchets: each total may only go down. + +- planning ids in comments; +- comment lines beyond 15 in a block; +- ALL-CAPS comment lines; +- non-English comment lines; +- line-number citations in code. + +`python3 scripts/check_text_hygiene.py tree --update-baseline` lowers `scripts/data/text_hygiene_baseline.json` after a cleanup. It never raises it, and CI rejects a raised baseline. + +Not checked by CI: the size limits, the platform, switch and lifetime-id rules, planning ids outside comments, English outside comments, and the regeneration step for generated code.