Conventional Commit Message Guidelines

The commit message should be structured as follows:

# A - inline command
git commit -m "<type>(optional scope): <commit message>"

# B - in a commit editor
<type>(optional scope): <description>

[optional body]

[optional footer(s)]

The commit contains the following structural elements, to communicate intent to the consumers of your library:

Commit Types

1. fix: A commit of the type fix patches a bug in your codebase (this correlates with PATCH in Semantic Versioning).

   Example: fix(authentication): prevent timing attack vulnerability

2. feat: A commit of the type feat introduces a new feature to the codebase (this correlates with MINOR in Semantic Versioning).

   Example: feat: add ability to create webhooks

3. build: A commit of the type build affects the build system or external dependencies (example scopes: gulp, broccoli, npm).

   Example: build: bump lodash from 4.17.15 to 4.17.21

4. chore: A commit of the type chore includes routine tasks, maintenance, or housekeeping changes that don't change production code.

   Example: chore: update .gitignore file

5. ci: A commit of the type ci affects the continuous integration or continuous delivery system (example scopes: Travis, Circle, BrowserStack, SauceLabs).

   Example: ci: add Node 14 to testing matrix

6. docs: A commit of the type docs affects documentation only.

   Example: docs(readme): update installation instructions

7. perf: A commit of the type perf improves performance.

   Example: perf: improve list rendering performance by virtualizing

8. refactor: A commit of the type refactor neither fixes a bug nor adds a feature, but restructures code.

   Example: refactor(user): extract address validation to separate function

9. revert: A commit of the type revert reverts a previous commit.

   Example: revert: feat(shopping cart): add product recommendations

10. style: A commit of the type style affects code formatting, white-space, etc., without changing logic.

    Example: style: fix indentation and whitespace

11. test: A commit of the type test adds missing tests or corrects existing tests.

    Example: test(api): add integration tests for user endpoints

12. hotfix: A commit of the type hotfix hot fix bugs in production. Example: hotfix: update config

Breaking Changes

BREAKING CHANGE: A commit that has a footer BREAKING CHANGE:, or appends a ! after the type/scope, introduces a breaking API change (correlating with MAJOR in Semantic Versioning). A BREAKING CHANGE can be part of commits of any type.

Example:

feat(api)!: require authentication for all endpoints

BREAKING CHANGE: All API endpoints now require authentication

Footers

Footers other than BREAKING CHANGE: <description> may be provided and follow a convention similar to git trailer format.

Example footers:

Reviewed-by: John Doe
Refs: AST-142
Co-authored-by: Jane Smith <jane@example.com>

Every commit that lands on main carries the Jira key of its subtask in a Refs: footer, so Jira lists the commit on the ticket (jira.md).

Best Practices

1. Keep the subject line concise (ideally under 72 characters)
2. Use the imperative mood in the subject line (e.g., "add" not "added" or "adds")
3. Do not end the subject line with a period
4. Separate subject from body with a blank line
5. Use the body to explain what and why vs. how
6. Reference the Jira key in the footer: Refs: AST-142