Media-Transport-Library

Coding standard guideline

1. One command

./checkpatch.sh                  # verify every tracked file -- what CI runs
./checkpatch.sh --staged         # verify staged files -- what the git hook runs
./checkpatch.sh --files a.c b.md # verify specific files
./format-coding.sh               # apply every autofix
./format-coding.sh --staged      # apply the autofixes to staged files only
./format-coding.sh --files a.c   # apply the autofixes to specific files
./format-coding.sh --check       # report, then restore -- same as --preview
./checkpatch.sh --install-hooks  # run the checks automatically on commit

Exit status is 0 clean, 1 findings, 2 a usage or environment problem. Verification runs the real fixers, so a failing run leaves their corrections in your working tree – git diff is the remediation. --preview is the mode that reports without mutating.

Nothing needs to be installed except pre-commit itself, which then installs a pinned copy of every linter into an isolated environment of its own. They do not need to be on your PATH, and the version you happen to have installed cannot change the result:

./checkpatch.sh --bootstrap      # tries pipx, then pip --user

§6.1 has the per-platform command if that fails.

2. One source of truth

                       .pre-commit-config.yaml         <-- rules live here
                       .github/linters/*               <-- and their rule content
                                  |
             +--------------------+--------------------+
             |                    |                    |
      ./checkpatch.sh      git pre-commit hook   .github/workflows/cicd-pr-check.yml
             |                    |                    |
        ./format-coding.sh    (same hooks)     (same hooks, Linux and Windows)

Every caller above runs the same hook list from the same file. None of them contains a rule, a version, a file filter or a tool invocation of its own:

File Owns Must never contain
.pre-commit-config.yaml which tool, which version, which arguments, which files nothing else does this
.github/linters/ rule content (.clang-format excepted, see below) tool selection or versions
.editorconfig encoding, line endings, and shfmt’s shell indent indent widths the formatters already own
.gitattributes line-ending normalization on checkout and check-in anything else
checkpatch.sh which files to feed the engine, how to report any rule
format-coding.sh thin write-mode wrapper over checkpatch.sh any rule
.github/workflows/cicd-pr-check.yml (lint jobs) orchestration: OS matrix, caching, Python setup any rule or config path
this document prose rationale and the parity table rules that are not in the config

Adding or changing a lint rule means editing .pre-commit-config.yaml (and the matching file in .github/linters/), and updating the parity table below. Nowhere else. A rule added to the workflow, to a script, or to a document is drift by construction, because only the config is what the hooks actually execute.

Bumping a tool version is its own commit, and its message quotes the blast radius from ./format-coding.sh --check. Never as a side effect of an unrelated change: that is how a wrong clang-format silently reformats hundreds of files. pre-commit autoupdate proposes the bumps.

2.1. Why .clang-format sits at the repository root

Every other rule file lives in .github/linters/, because that is where super-linter looks. .clang-format cannot: clang-format itself searches upward from each source file, so the file has to be at the root, and it is a real file, not a symlink. A Windows checkout without symlink support materializes a symlink as a text file containing a path, at which point clang-format silently finds no configuration and falls back to plain LLVM style – a whole-tree reformat waiting to happen.

3. What is checked

Language Tool Fixes Rule file
any pre-commit-hooks 6.0.0 – five structural guards no –
C, C++ clang-format 23.1.3 yes .clang-format
Python isort 9.0.2 (--profile black) yes –
Python black 26.10.1 (--line-length 88) yes –
Python flake8 7.4.1 no .github/linters/.flake8
Python ruff 0.17.1 partly .github/linters/.ruff.toml
Shell shfmt 3.14.1 yes .editorconfig ([*.sh])
Shell shellcheck 0.11.0 no –
Markdown markdownlint-cli 0.49.1 yes .github/linters/.markdown-lint.yml
Markdown prose textlint 15.8.0 + terminology 4.0.1 yes .github/linters/.textlintrc
YAML yamllint 1.38.0 no .github/linters/.yaml-lint.yml
GitHub Actions actionlint 1.7.12 no .github/linters/actionlint.yaml
HTML htmlhint 1.9.2 no .github/linters/.htmlhintrc
staged diff gitleaks 8.30.1 no –
CI path filters .github/scripts/ci/lint/check-path-filters.py no .github/path_filters.yml
commit message gitlint 0.19.1 no .github/linters/.gitlint

The gitlint row is the one hook that does not run over files. It runs at the commit-msg stage against the message being written, so ./checkpatch.sh – which lints files and has no message to read – never triggers it; the git commit-msg hook fires it locally and CI runs the same hook over a pull request’s commits. §7 has the split between what its regular expression enforces and what still needs a reviewer.

Read the gitleaks row narrowly. Its hook is gitleaks git --pre-commit --staged, so it scans the staged diff and cannot scan a whole tree – in --all-files mode nothing is staged and it passes trivially. It catches a secret you are about to commit; whole-tree and pull-request scanning is CI’s, in the parity table below.

A rule file must name its rules, and an argument that matters must be written down. Both halves of that were learned the hard way here:

flake8 and ruff both run, and the overlap is deliberate rather than accidental. .ruff.toml selects E, W, F – flake8’s own rule set, since flake8 declares no select either – so the two are as close to interchangeable as they can be. They are not yet interchangeable in one direction: ruff 0.17 does not implement F824 (“dead global declaration”) at all; ruff rule F824 answers “unknown rule”. flake8 7.3 found two of them here, both genuinely dead. That single rule is the whole reason the flake8 hook still exists, which is also why its rule set is mirrored rather than extended – when ruff grows F824, retiring flake8 is a delete and not a re-measurement.

The five pre-commit-hooks entries are not style checks. Each one mechanically guards a promise made elsewhere in this document and otherwise enforced by nothing: destroyed-symlinks guards §2.1, check-illegal-windows-names and mixed-line-ending guard §6, check-merge-conflict is universal, and detect-private-key is the only secret scan that runs in a bare whole-tree ./checkpatch.sh – see the gitleaks note above for why that gap exists.

A version bump may not smuggle in a rule change, and three of the bumps in this set tried to:

pymtl_wrap.c (SWIG-generated) and vmlinux.h (kernel-generated) are excluded from clang-format.

patches/ is a vendored third-party patch series: reformatting a byte of it would break git apply. That started life as a global exclude: ^patches/, and a global exclude was the wrong shape twice over. It protected nothing – every formatter here is selected by language type, a *.patch file is none of those types, and deleting the exclude changed no hook’s result on the whole tree. And it silently disabled check-illegal-windows-names, which reads paths rather than content and so was the one hook the exclude could actually reach. With the hook blinded, patches/dpdk/26.03/0012-net-ice-e830:-...patch sat in the tree with a colon in its name; git checkout on Windows rejects that outright with error: invalid path and exit 128, so the repository could not be cloned there at all and the Windows CI job died during checkout, before any linter ran. The file is renamed and the exclusion now sits on mixed-line-ending – the only hook that reads every file regardless of type – and nowhere else.

C/C++ style is whatever .clang-format says – BasedOnStyle: Google with ColumnLimit: 90 today. Changing it rewrites the entire tree, so it is its own commit or it is a mistake.

Two things about clang-format 22 are worth knowing before the next bump, because both were paid for once already. It no longer reads (type)-1 as a cast, so ((mtl_iova_t)-1) is now written ((mtl_iova_t) - 1); that is whitespace only and the tokens are identical, and in the ((align)-1) case – a macro parameter, not a type – the new spacing is simply correct. And from 18 on, a braced initializer whose elements carry trailing comments is broken to one element per line. The six le10_to_be_* permute tables in lib/src/st2110/st_avx512_vbmi.c are laid out one pixel group per row precisely so the pattern can be read against the packing it implements, so they sit inside a /* clang-format off */ region. That is a pin on the layout, not an exemption from review: reformatting them cost 480 lines and all of their readability.

Rules the language tools cannot express – the two-world rule, prefixes, lock order, error-return conventions – are in .github/instructions/mtl-c-coding.instructions.md and enforced by review, not by a linter.

3.1. Deliberate omissions

Not every available check is enabled. These were considered and rejected, so that “why isn’t there a hook for X” has an answer:

4. Parity table: local, hook and CI

The three must agree. Anything CI enforces that checkpatch.sh cannot reproduce is listed here explicitly, and runs in the residual-linters job of .github/workflows/cicd-pr-check.yml.

CI check Status Why
clang-format, isort, black, flake8, ruff, shfmt, shellcheck, markdownlint, textlint, yamllint, actionlint, htmlhint in checkpatch.sh pinned by .pre-commit-config.yaml; each pin measured clean over the whole tree before adoption
VALIDATE_GITLEAKS residual the hook scans the staged diff, so it cannot scan a whole tree or a pull request. Both run the same scanner at different scopes. detect-private-key covers the whole tree, but only for PEM blocks
VALIDATE_BASH_EXEC residual *.sh must keep its executable bit. No upstream hook has these exact semantics; the nearest one is broader and fails 17 files
VALIDATE_ENV (dotenv-linter) dropped the slim image had no dotenv-linter before super-linter 6.8.0, so it never ran. From there on it fails all 11 tracked *.env, most of them path manifests rather than dotenv files
VALIDATE_TYPESCRIPT_ES residual 135 *.ts files with no lintable project configuration from a clean clone: .gitignore’s blanket *.json leaves tests/tools/perf_debug_mcp/package.json untracked. .github/linters/eslint.config.mjs keeps it the parse check super-linter v6 ran
VALIDATE_RUST_*, VALIDATE_RUST_CLIPPY residual rustfmt and clippy need a Rust toolchain per environment. Carried over unchanged rather than narrowed, since narrowing the edition list would be a rule change
VALIDATE_EDITORCONFIG dropped it was default-on before, and enforced nothing: no .editorconfig existed. The one that exists now declares only charset, end_of_line and shfmt’s shell indent, all of which the hooks or .gitattributes already cover
commit-message style (gitlint) own commit-messages job a message is not a file, so checkpatch.sh cannot reach it. The job runs the same commit-msg hook over each PR commit that the git commit-msg hook runs locally, so version and rules stay in one place. Not in residual-linters: that is the super-linter allow-list, and MTL’s capitalized, scope-free format is not one
Bandit bandit job of cicd-pr-check.yml a security scan with a mandated test set, not a style rule. The test set is .github/code-scan/bandit.config, apart from the linter configs in .github/linters/. task ci:bandit reproduces the scan locally, with the Bandit release pinned in .github/code-scan/requirements.txt, which Dependabot updates
clang-tidy, on the C and C++ lines a pull request changes own clang-tidy job in cicd-pr-check.yml it needs the compile commands of configured builds, which checkpatch.sh has no part in. The checks are .clang-tidy’s, run by cpp-linter/cpp-linter-action; the report is the clang-tidy-report artifact. After ./build.sh, clang-tidy-20 -p build <file> runs them on one file locally

That job was a deny-list of nine VALIDATE_*: false keys and is now an allow-list, so anything not named above is no longer enforced – the two real cases are in the table, and a file type census found no tracked *.js, *.css, *.xml, *.go, *.rb, *.java or *.sql for the rest to have applied to. super-linter aborts if true and false are mixed, so no VALIDATE_*: false line may be added back.

4.1. The build waits for the file linters

The build job of .github/workflows/cicd-pr-check.yml needs the checkpatch matrix jobs and residual-linters (Lint checks not yet in checkpatch). A lint failure therefore skips the build rather than wasting a DPDK compile on it, and ci-result fails. The ci-result job is the one branch-protection check for the workflow. It requires the file linters and commit-message check on pull requests. Commit-message style does not block the compile.

The coupling is by job ID in needs:, in one workflow, so GitHub refuses a rename of a lint job that does not also change the build job.

5. Git hooks

./checkpatch.sh --install-hooks

Installs the pre-commit, pre-merge-commit and commit-msg hooks. The first two check staged files only, so they cost roughly the size of your change, not the size of the tree; the third runs gitlint over the message you are writing (§7).

To bypass in an emergency:

git commit --no-verify
git merge --no-verify

Bypassing is for a work-in-progress commit or a broken hook, not for merging unformatted code: CI runs the identical hook list and is the merge authority.

One surprise worth knowing before it costs you ten minutes: if .pre-commit-config.yaml itself has unstaged modifications, the hook refuses to run at all and every commit fails with Your pre-commit configuration is unstaged. Stage the config, or use --no-verify while you iterate on it.

6. Platforms

Any Linux distribution, macOS and Windows (git-bash / MSYS2) are supported, and CI runs ./checkpatch.sh on Linux and Windows. The cross-platform claim had already rotted once before that job existed: a tracked filename containing a colon made the tree impossible to check out on Windows (see the patches/ note in §3). check-illegal-windows-names now fails locally on any path Windows cannot represent, which is a cheaper place to find out.

6.1. Installing the engine

You need git, Python 3.10 or newer (what pre-commit 4.x requires), and network access on the first run. Nothing else – no distribution package of clang-format, shfmt, shellcheck, Node.js or Go.

./checkpatch.sh --bootstrap           # pipx if present, else pip --user

Most current distributions mark their system Python as externally managed (PEP 668), which makes pip install --user fail. That is not a broken repository – it means you should take the distribution’s own package, or pipx:

Platform Command
Fedora, RHEL, CentOS Stream sudo dnf install pre-commit
Arch, Manjaro sudo pacman -S python-pre-commit
Debian, Ubuntu sudo apt install pre-commit
openSUSE sudo zypper install python3-pre-commit
macOS brew install pre-commit
Windows, git-bash / MSYS2 py -m pip install pre-commit
anything with pipx pipx install pre-commit

Then, once per clone:

./checkpatch.sh --install-hooks

The first run builds the pinned tools into ~/.cache/pre-commit – about 560 MB and a few minutes, once per .pre-commit-config.yaml change. PRE_COMMIT_HOME moves it, which is what CI does to keep the cache workspace-relative.

Ten hooks are Python wheels; the other four need no system toolchain either. gitleaks is a Go hook and pre-commit downloads Go itself when it is not on PATH. markdownlint, textlint and htmlhint are Node hooks, and the config pins default_language_version: node so pre-commit fetches that exact Node rather than using whatever the host has – markdownlint-cli 0.49 needs Node 20 or newer merely to parse its own source, so an older system Node was a crash and a newer one was an unpinned variable.

One thing genuinely not pinned is the engine: the config’s floor is minimum_pre_commit_version: 3.5.0, CI runs the release that .github/linters/requirements.txt locks, and a distribution package may be older than either. If a hook behaves differently for you than in CI, check pre-commit --version first – CI is authoritative.

6.2. What the scripts avoid

7. Commit messages

MTL follows Conventional Commits with two deviations: structural elements are capitalized, and Add is accepted for feat plus build(deps) for dependency bumps.

The mechanical half of that format is automated, by gitlint. The commit-msg git hook runs it on every git commit locally, and the commit-messages job in .github/workflows/cicd-pr-check.yml runs the same hook over each commit a pull request adds. checkpatch.sh itself still checks only files – it has no message to read – so message linting rides the commit-msg stage, not a checkpatch.sh run. The rules are in .github/linters/.gitlint, the version is pinned in .pre-commit-config.yaml, and both callers run the one hook, so they cannot drift.

gitlint enforces what a regular expression can judge: the type prefix comes from the fixed set above, capitalized; a capital follows it; the subject is at most 72 characters with no trailing period; and git commit -s’s Signed-off-by trailer is present. It deliberately does not use its own conventional-commit rule, which wants a lowercase feat: with scopes – the opposite of MTL’s format. Body-line wrapping is left off because a valid Fixes: or Signed-off-by footer legitimately runs past 72 and would false-positive.

Everything the mtl-commit skill asks for that a regular expression cannot judge – imperative mood, “explain why, not how”, no chat-or-process leakage, body wrapping – stays a reviewer’s call, in the same bucket as the two-world rule and the prefixes in .github/instructions/mtl-c-coding.instructions.md.

8. Diagram colors

The diagrams in doc/png/ use the five palette colors.

Color Hex Use
Intel Classic Blue #0068B5 The MTL logo, png/mtl_logo.svg
Hex Use in the diagrams
#1F271B Text, lines, arrows and borders
#0B4F6C Session blocks and the control plane panel
#145C9E The MTL block and the data plane panel
#CBB9A8 Group panels, for example Pipeline API and Device
#DCC7BE Page background and labels

The logo letters are polygons. Thus, installed fonts do not change the logo.