Commit messages

Read the diff and write the message for a reviewer who sees only the title and the summary. Commit with sl where the repo is a Sapling checkout, and with git everywhere else.

Title

• Imperative, concise and specific: "Fix retry loop in uploader", not "Fixed bug". Around 72 characters, no full stop, plain text with no Markdown.
• Prefix it with the scope the change targets, scope: Subject, where the scope answers where: a directory, package, subsystem or file. Match the repo's history, git log --no-merges -20 -- <paths you touched>, including the capitalization after the prefix. Square brackets are markers before the scope, [WIP] or [RFC], or a tuple where the repo uses one, such as React Native's [General][Fixed].

Summary

Two to four sentences, or an opening sentence and a few short bullets, that say what changed and why. Open with the problem as the code behaves today, or with the change as an imperative; never with a result described as a state. Keep what a reviewer acts on: the motivation, behavior a user or caller can observe changing, a decision they might question, a caveat that affects whether it should land, and cross-references such as Fixes #123. Leave out what the diff already shows: renames, moved helpers, changed signatures, the order the work happened in, and test results, which go in the test plan.

Bold headings, each on its own line with a blank line before and after, when the summary has two or more parts: