Git commit subject line conventions

commit.md

Conventions for structuring Git commit subject line

Follow Git best practices: use imperative mood, and try to limit it to 50 characters or so.

Structure

Instead of a simple sentence, prefer to use a Linux-style component prefix:

<name>: <comment>

Instead of writing Fix nasty bug in <name> write <name>: fix nasty bug (not capitalized). Only if the change truly is project-wide, write Change license terms (capitalized). The rationale for not always capitalizing the comment is that the whole line should form a single phrase.

Component

Choosing the component prefix may be hard.

• If the change affects a single technical component with a specific name, use it. Spell it exactly: runtime, StringBuilder, super-command.
• If the change affects an abstract feature, give it a capitalized name: Userspace.
• In a complex project there may be nested components. Use filesystem layout if applicable (syscall/fork: …), or if abstract names are involved, use separate prefixes (Userspace: macOS: …). Avoid nesting if the context is clear enough from a single layer.

It's ok to have varying level of detail. The messages are for humans, not computers; the exact details are in the commit contents.

If it's hard to come up with the correct component names or scope, think of a phrase like "Mend breakage in class FooObject of subsystem foo." If that's the message you'd like to convey to the reader, write FooObject: mend breakage.

Examples

Change license terms
runtime: add garbage collector
core/runtime: add garbage collector
StringBuilder: reduce allocations
lib/StringBuilder: reduce allocations
super-command: add -f option
tools/super-command: add -f option
Userspace: fix backward-compatibility with 32-bit ABI
Userspace: macOS: add support
macOS: refactor integer types in syscall ABIs