Understanding Conventional Commits

Conventional commits follow a structured format that makes commit history

more meaningful and easier to understand. This guide explains the conventions
that are part of the “Conventional Commits” specification.

Basic Structure
A conventional commit message follows this format:
type(scope): description

[optional body]

[optional footer]

Types of Commits
Feature Additions (feat:)
When you’re adding new functionality to your codebase, use the feat: prefix.
For example:
feat(auth): implement JWT authentication system
feat(cart): add product quantity adjustment buttons
feat(api): create endpoint for user preferences

Bug Fixes (fix:)

When resolving bugs or issues in your code, use the fix: prefix:
fix(checkout): prevent total calculation error with empty cart
fix(auth): resolve token exposure in error logs
fix(ui): correct button alignment on mobile devices

Maintenance Tasks (chore:)

For tasks that don’t modify source code but are related to maintenance, use
chore::
chore(deps): update React to version 18.2
chore(cleanup): remove deprecated config files
chore(build): update webpack configuration

Documentation Updates (docs:)

When modifying documentation or comments, use the docs: prefix:
docs(api): add examples for new endpoints
docs(readme): add deployment instructions

1
docs(comments): add type definitions for user service

Code Style Changes (style:)

For changes that don’t affect code behavior but improve its style, use style::
style(lint): apply prettier formatting
style(naming): convert variables to camelCase
style(spacing): standardize indentation in CSS

Code Refactoring (refactor:)

When restructuring existing code without changing its behavior, use refactor::
refactor(auth): split authentication logic into separate service
refactor(perf): replace recursive function with iteration
refactor(cleanup): simplify error handling logic

Test Modifications (test:)

When working with tests, use the test: prefix:
test(api): add integration tests for user registration
test(e2e): improve reliability of checkout flow tests
test(unit): add tests for cart calculation

Performance Improvements (perf:)

For changes that improve application performance, use perf::
perf(db): add index for frequent searches
perf(frontend): implement lazy loading for images
perf(build): remove unused dependencies

Understanding Scope
The scope (written in parentheses) indicates the area of code being changed.
Common scopes include:
• Feature areas: (auth), (cart), (users)
• Technical areas: (api), (db), (ui)
• Components: (Button), (Header), (Footer)

Best Practices for Commit Messages

1. Use imperative mood in your descriptions (e.g., “add” not “added”)
2. Keep the first line under 72 characters
3. Provide detailed explanations in the commit body when needed
4. Reference related issue numbers in the footer

2
Example of a Complete Commit Message
feat(auth): implement password reset functionality

- Add reset password email sender

- Create reset token generation
- Add password update endpoint
- Implement frontend reset form

Closes #123
Breaking change: requires new EMAIL_SERVICE_KEY env variable

Learning Resources
To deepen your understanding of conventional commits, explore these resources:
1. Official Conventional Commits Specification
2. Angular’s Commit Message Guidelines
3. Commitlint Documentation

Additional Notes
• Conventional commits help automate semantic versioning and changelog
generation
• They make it easier for teams to understand and track changes
• Many tools and CI/CD pipelines can parse these commit messages for
automated processes
• Using consistent conventions helps maintain a clean and professional git
history
Remember that these conventions are guidelines meant to improve clarity and
consistency in your project’s history. While they may seem formal at first,
they become natural with practice and provide significant benefits for project
maintenance and collaboration.
Angular guidelines

Commit Message Format

This specification is inspired by and supersedes the [AngularJS commit message
format][commit-message-format].
We have very precise rules over how our Git commit messages must be formatted.
This format leads to easier to read commit history.
Each commit message consists of a header, a body, and a footer.
<header>
<BLANK LINE>

3
<body>
<BLANK LINE>
<footer>
The header is mandatory and must conform to the Commit Message Header
format.
The body is mandatory for all commits except for those of type “docs”. When
the body is present it must be at least 20 characters long and must conform to
the Commit Message Body format.
The footer is optional. The Commit Message Footer format describes what
the footer is used for and the structure it must have.

Commit Message Header

<type>(<scope>): <short summary>
� � �
� � ��� Summary in present tense. Not capitalized. No period at the end.
� �
� ��� Commit Scope: animations|bazel|benchpress|common|compiler|compiler-cli|core|
� elements|forms|http|language-service|localize|platform-browser|
� platform-browser-dynamic|platform-server|router|service-worker|
� upgrade|zone.js|packaging|changelog|docs-infra|migrations|
� devtools
�
��� Commit Type: build|ci|docs|feat|fix|perf|refactor|test
The <type> and <summary> fields are mandatory, the (<scope>) field is op-
tional.

Type Must be one of the following:

• build: Changes that affect the build system or external dependencies
(example scopes: gulp, broccoli, npm)
• ci: Changes to our CI configuration files and scripts (examples: Github
Actions, SauceLabs)
• docs: Documentation only changes
• feat: A new feature
• fix: A bug fix
• perf: A code change that improves performance
• refactor: A code change that neither fixes a bug nor adds a feature
• test: Adding missing tests or correcting existing tests

Scope The scope should be the name of the npm package affected (as per-
ceived by the person reading the changelog generated from commit messages).
The following is the list of supported scopes:

4
 • animations
• bazel
• benchpress
• common
• compiler
• compiler-cli
• core
• elements
• forms
• http
• language-service
• localize
• platform-browser
• platform-browser-dynamic
• platform-server
• router
• service-worker
• upgrade
• zone.js
There are currently a few exceptions to the “use package name” rule:
• packaging: used for changes that change the npm package layout in all
of our packages, e.g. public path changes, package.json changes done to
all packages, d.ts file/format changes, changes to bundles, etc.
• changelog: used for updating the release notes in CHANGELOG.md
• dev-infra: used for dev-infra related changes within the directories
/scripts and /tools
• docs-infra: used for docs-app (angular.dev) related changes within the
/adev directory of the repo
• migrations: used for changes to the ng update migrations.
• devtools: used for changes in the browser extension.
• none/empty string: useful for test and refactor changes that are done
across all packages (e.g. test: add missing unit tests) and for docs
changes that are not related to a specific package (e.g. docs: fix typo
in tutorial).

Summary Use the summary field to provide a succinct description of the

change:
• use the imperative, present tense: “change” not “changed” nor “changes”
• don’t capitalize the first letter
• no dot (.) at the end

5
Commit Message Body Just as in the summary, use the imperative, present
tense: “fix” not “fixed” nor “fixes”.
Explain the motivation for the change in the commit message body. This commit
message should explain why you are making the change. You can include a
comparison of the previous behavior with the new behavior in order to illustrate
the impact of the change.

Commit Message Footer The footer can contain information about break-
ing changes and deprecations and is also the place to reference GitHub issues,
Jira tickets, and other PRs that this commit closes or is related to. For example:
BREAKING CHANGE: <breaking change summary>
<BLANK LINE>
<breaking change description + migration instructions>
<BLANK LINE>
<BLANK LINE>
Fixes #<issue number>
or
DEPRECATED: <what is deprecated>
<BLANK LINE>
<deprecation description + recommended update path>
<BLANK LINE>
<BLANK LINE>
Closes #<pr number>
Breaking Change section should start with the phrase BREAKING CHANGE: fol-
lowed by a summary of the breaking change, a blank line, and a detailed de-
scription of the breaking change that also includes migration instructions.
Similarly, a Deprecation section should start with DEPRECATED: followed by a
short description of what is deprecated, a blank line, and a detailed description
of the deprecation that also mentions the recommended update path.

Revert commits
If the commit reverts a previous commit, it should begin with revert:, followed
by the header of the reverted commit.
The content of the commit message body should contain:
• information about the SHA of the commit being reverted in the following
format: This reverts commit <SHA>,
• a clear description of the reason for reverting the commit message.