PR and Commit format

Review-ready PRs and commit history must use a consistent, scannable title format. The format only describes the deliverables and does not record the interim work process.

PR title

PR titles should be uniformly used:

prefix: subject

The title must naturally form the following sentence and accurately describe the complete diff:

This PR changes {prefix} to {subject}.

Rules:

• prefix represents the main ownership or contract that was changed, using lowercase letters, numbers, hyphens or /, and cannot contain spaces, empty segments or the first and last /.
• Leave a space after the colon.
• subject Use a base verb phrase starting with lowercase, which must be able to be directly followed by to and describe the final result of the merger.
• Do not use a period at the end, do not write the Issue/PR number in the title, and do not retain process descriptions such as WIP, draft, fixup, address review or misc changes.
• A PR has only one main prefix. For cross-module changes, use the module with the source contract; for repository-level changes, use repo.

Example:

apps/mobile: add app-wide localization support
api: add source-qualified workflow RPC
guides/reviewing: document PR and commit format
repo: close deterministic validation gaps

Each of these titles can be read as:

This PR changes apps/mobile to add app-wide localization support.
This PR changes api to add source-qualified workflow RPC.
This PR changes guides/reviewing to document PR and commit format.
This PR changes repo to close deterministic validation gaps.

Commit title

Each review-ready commit uses the same format as a PR:

prefix: subject

All rules regarding prefix, subject, capitalization, ownership, and finality in the PR title apply unchanged to the commit. The commit title must accurately describe the diff of the commit. In order to match the PR title, multiple unrelated ownership or independent targets cannot be stuffed into the same commit.

The Commit title is tested using the same sentence:

This commit changes {prefix} to {subject}.

Commit content

• A commit has only one independently interpretable purpose; unrelated fixes, formatting, build artifacts, or dependency changes should be separated.
• When the title has fully expressed the cause and result, the body does not need to be written.
• When body is required, leave a blank line after the title, first explaining why the change is needed, and then describing any behavior, boundaries, or compatibility implications that are not directly derived from the diff.
• For larger commits, sections such as Summary, Impact and Validation can be used; the verification command must be a truly executed command, and unrun checks cannot be written as passed.
• The Source Schema and the committed generated outputs generated by it should be in the same atomic change, unless the Issue explicitly requires phased delivery.
• Temporary fixup!, squash!, WIP, merge residue and commits with only "address review comments" must not appear in review-ready history.
• Do not write secrets, credentials, private paths, machine states, log dumps, or tool signatures unrelated to the change.

Example:

guides/reviewing: document PR and commit format

Define the title contract used by review-ready PRs and commits so reviewers
can reject ambiguous or process-only history before merge.

Review check

Confirm before PR enters review-ready or merge status:

• PR title matches prefix: subject and accurately covers the final diff;
• Each reserved commit title and bounds conform to this specification;
• Review modifications have been organized into meaningful commits, and temporary process commits are not retained;
• The final title used by squash merge still complies with this specification, and the PR number automatically appended by GitHub is not part of the title input.