linuxmsm/qdl

0 Fork 0

mirror of https://github.com/linux-msm/qdl.git synced 2026-10-07 06:29:17 -07:00

Files

T

Igor Opaniuk 6c47f1cb7c doc: fix markdown lint findings in AGENTS.md and RELEASING.md

Preparation for linting every markdown file in the tree: surround the
sign-off example in AGENTS.md with the blank lines the linter wants,
and flatten the RELEASING.md table of contents - its single top-level
entry only repeated the document title, and the nested indentation
tripped the linter's list-indent rule under kramdown.

While at it, replace the literal Signed-off-by example with the
'git commit -s' command that produces it. checkpatch validates
anything shaped like a signature tag on any patch line - added,
removed and context lines alike - so any patch touching these lines
trips 'Unrecognized email address' on the $(git config ...)
placeholders. Documenting the command instead keeps trailer-shaped
text out of the file entirely, with no checkpatch exceptions needed.

Signed-off-by: Igor Opaniuk <igor.opaniuk@oss.qualcomm.com>

2026-07-21 14:03:19 +02:00

3.7 KiB

Raw Permalink Blame History

Agent Guide for QDL

This file guides automation agents working in the QDL repository. Human contributors should read CONTRIBUTING.md; this document captures the same rules in a form suited to automated workflows.

Project overview

QDL is a command-line tool for flashing firmware on Qualcomm-based devices over USB in Emergency Download (EDL) mode. It uploads a flash loader to the device and drives it using the Sahara and Firehose protocols.

Prerequisites and build

Linux

sudo apt install libxml2-dev libusb-1.0-0-dev libzip-dev meson ninja-build help2man
meson setup build
meson compile -C build

macOS (Homebrew)

brew install libxml2 libusb libzip meson ninja help2man
meson setup build
meson compile -C build

macOS (MacPorts)

sudo port install libxml2 libusb libzip meson ninja help2man
meson setup build
meson compile -C build

Before committing

Every change must build cleanly and pass the style and test checks. Run:

meson setup build              # once, or after changing meson.build
meson compile -C build         # build must succeed
meson test -C build            # run the test suite
meson compile check -C build   # checkpatch (Linux kernel style)
meson compile markdown-lint -C build   # lint Markdown sources

To check only staged changes against coding style, use meson compile check-cached -C build. To validate a whole series the way CI does (per-commit, patch mode), use meson compile check-range -C build.

Coding style

Follow the Linux kernel coding style.
Style violations are caught by the check / check-cached targets above.
Use ASCII only. Neither code, documentation, nor commit messages may contain non-ASCII characters. Replace them with ASCII alternatives, e.g. use - or -- instead of en/em dashes, straight ' and " instead of typographic quotes, and ... instead of an ellipsis character.
Use appropriate SPDX license identifiers in sources files

Commit conventions

Every commit message must follow the repository convention:

The subject must carry a subsystem tag. Prefix it with the affected subsystem, followed by a lowercase, imperative summary, e.g. usb: add support for listing devices, firehose: report progress through the skipblock fast-path, github: package self-contained binaries on Linux and macOS. Common prefixes include qdl, usb, sahara, firehose, program, vip, ramdump, tests, github, meson, README, and doc. Use github: (not ci:) for CI and workflow changes.
The commit must have a body explaining the rationale - why the change is needed and any key design decisions - not just what changed. The subject alone is not sufficient for anything beyond a trivial fix.
Keep the subject short and specific; capture intent, not a file-by-file dump.
Use the imperative mood (Add, Update, Drop, Enable, Revert).
Wrap body lines at ~72 characters.
Do not mix unrelated changes in one commit; split them logically.
Each patch must be logically coherent, self-contained, and independently buildable. The tree must remain functional after every commit.

Sign-off

Every commit must carry a Signed-off-by trailer using the identity from the local git configuration, as appended by git commit -s:

git commit -s

When committing programmatically, AI agents MUST NOT add Signed-off-by tags, only a human can certify the Developer Certificate of Origin (DCO). Do not add any other trailers (for example, co-author trailers).

Submitting

Submit patches against the master branch as a GitHub pull request: fork the repo, create a branch, do the work, rebase onto upstream, and open the PR.

3.7 KiB Raw Permalink Blame History