Skip to content

Instantly share code, notes, and snippets.

@ljharb

ljharb/commit-conventions.md

Created April 6, 2022 18:17
Show Gist options
  • Star 1 You must be signed in to star a gist
  • Fork 1 You must be signed in to fork a gist
  • Save ljharb/772b0334387a4bee89af24183114b3c7 to your computer and use it in GitHub Desktop.
Save ljharb/772b0334387a4bee89af24183114b3c7 to your computer and use it in GitHub Desktop.
Download ZIP
Commit Message Conventions
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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment