How to Git Commit
Quick Reference: See Git Commit Reference for syntax and examples.
Commit Message Guidelines
We use the conventional commits specification to ensure a consistent commit history.
Commit Message Format
<type>(<scope>): <short description>
type: Defines the type of change (e.g.,feat,fix,docs,style,refactor,test,chore).scope: Indicates the specific app, library, or area of the repository affected by the change (e.g.,app-1,shared-utils,infra).short description: A concise description of the change (imperative mood, lowercase).
Commit message with description
Commit message with scope
Full example
Subject
A concise summary of the changes, prefixed by a type and a colon.
Example: feat(handbook): add new section
Body (optional)
A more detailed explanation of the changes.
Example: Added user login instructions.
Trailer
Metadata or additional information about the commit.
Example: Changelog: added
Branching Strategy
To keep the repository organized and ensure changes are easily identifiable, all branches must follow the naming convention described below. This helps differentiate between work on specific applications, libraries, or infrastructure.
<type>/<task-id>
type: Indicates the purpose of the branch. The following types are commonly used:feat: For new features or enhancements.fix: For urgent or critical fixes in production.chore: For non-functional updates like tooling, dependencies, or build scripts.
task-id: The task ID from your issue tracker (e.g., GitLab, Jira).
Examples
For a new feature in an app
For a hotfix in a library
Enforcing Standards with Husky (optional)
To help enforce commit message standards, Husky can be applied. Husky manages Git hooks and ensures that commits follow the required format by running scripts before commits are finalized.
Husky Integration: Husky can be configured to run commitlint, which checks your commit messages against the project’s conventions.
Supported Types
Use the following types to describe the nature of your commit in the subject line:
| Type | Description |
|---|---|
| feat | A new feature. |
| fix | A bug fix. |
| docs | Documentation only changes. |
| style | Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc). |
| refactor | A code change that neither fixes a bug nor adds a feature. |
| perf | A code change that improves performance. |
| test | Adding missing or correcting existing tests. |
| chore | Changes to the build process or auxiliary tools and libraries such as documentation generation. |
Automated Release Notes with CHANGELOG
Adhering to commit message conventions plays a crucial role in generating automated release notes:
- Commit Conventional Enforcement: Ensuring commit messages follow the standardized format helps in the automatic generation of release notes.
- CHANGELOG: Using appropriate changelog trailers (e.g., Changelog: added, Changelog: fixed) ensures that changes are accurately reflected in the CHANGELOG
- Automation: Tools can parse commit messages to automatically compile and update the changelog. This automation improves the efficiency and accuracy of release note generation, saving time and reducing errors.