Commit Message Conventions

commit-conventions.md

Commit Message Conventions

This is a rough sketch of the commit message conventions I follow.

Format

[$Category] `$Component`: short summary

Fixes #123. See #456.

In this example, $Category is one of the categories listed below.

$Component depends on the context and the project - in a project like https://github.com/ljharb/qs, the components might be parse and stringify. In a project like https://github.com/ljharb/es-abstract, the components would include a spec year (ES2015, ES2017+, etc), and also an abstract operation name.

Multi-package Repos

In a repo with multiple packages, when a commit touches any subpackages (as opposed to just the root), the commit message should be prefixed with one of:

• [*] : all packages
• [foo] : the "foo" package
• [foo-{bar,baz}] : the "foo-bar" and "foo-baz" packages (ie, bash expansion syntax)
• [foo-bar | foo-baz]: an alternative to comma-separation, but doesn't allow bash expansion

Categories

• Breaking: anything semver-major
• New: anything semver-minor
• Deps: anything that just updates runtime or peer deps
• Dev Deps: anything that only affects dev deps
• readme: anything that's only changing the readme
• Docs: anything that changes API documentation (more than just the readme)
• Robustness: a refactor (semver-patch) that makes the package more robust against environment breakage (people modifying builtin JS methods, for example)
• Performance: a refactor (semver-patch) that improves performance (sometimes Perf, be consistent with what's in the log already)
• Refactor: no observable changes (semver-patch)
• actions: anything that only changes Github Actions workflows
• Tests: anything to do with testing, that's not just updating dev deps (sometimes Test, but the plural is preferred)
• eslint: anything that's solely to do with linting - config and/or code changes, eg.
• meta: anything to do with project infra not covered by a more specific category: random package.json stuff, github config files, etc
• patch: anything semver-patch not covered by a more specific category

Category names typically use the capitalization above, but it's also acceptable to "always lowercase", for consistency.

Miscellaneous

When a commit has multiple authors, I use Github's coauthorship metadata:

Co-authored-by: Name Here <email@here>

These lines must be the last lines of the entire commit message, or Github will fail to identify them.

I try to always include a Co-authored-by line for every author, even the one whose authorship is already on the commit. When I include myself, I usually put myself last - but otherwise, I lightly sort them by "amount of work, descending". The order doesn't really matter here, of course.