ljharb/commit-conventions.md

## commit-conventions.md

      
    Raw
  

              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.