Contributing to MobileGL

These rules keep the code and its history readable. scripts/check_text_hygiene.py checks the ones listed under 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 <the reverted subject>.

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 <base> from the same package formats only the lines changed since <base>. 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.
docs/archive/ keeps the planning notes and agent contracts of the disaggregation work as they were. It is frozen: no file there is added, edited or removed.

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 (moving a file is not adding it);
any change under docs/archive/;
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.

6.6 KiB Raw Blame History