fcc3d3a3b7
Add commit-memo tool that provides a comprehensive cheatsheet for conventional commits including structure, examples, and common tools. - Implements markdown-based content display - Covers all conventional commit elements (type, scope, description, body, footer) - Includes examples and common tooling (commitizen, commitlint, husky, etc.) - Follows established tool architecture pattern
164 lines
3.6 KiB
Markdown
164 lines
3.6 KiB
Markdown
# Conventional Commits Cheatsheet
|
|
|
|
## Structure
|
|
|
|
A conventional commit message follows this structure:
|
|
|
|
```
|
|
<type>[optional scope]: <description>
|
|
|
|
[optional body]
|
|
|
|
[optional footer(s)]
|
|
```
|
|
|
|
## Elements
|
|
|
|
### Type (Required)
|
|
The type describes the kind of change being made. Common types include:
|
|
|
|
- **feat**: A new feature for the user
|
|
- **fix**: A bug fix for the user
|
|
- **docs**: Documentation changes
|
|
- **style**: Code style changes (formatting, missing semicolons, etc.)
|
|
- **refactor**: Code changes that neither fix a bug nor add a feature
|
|
- **test**: Adding or updating tests
|
|
- **chore**: Maintenance tasks, dependency updates, build changes
|
|
- **perf**: Performance improvements
|
|
- **ci**: Changes to CI/CD configuration
|
|
- **build**: Changes to build system or external dependencies
|
|
- **revert**: Reverting a previous commit
|
|
|
|
### Scope (Optional)
|
|
The scope provides additional context about what part of the codebase is affected:
|
|
|
|
```
|
|
feat(auth): add OAuth2 integration
|
|
fix(api): resolve timeout issues
|
|
docs(readme): update installation instructions
|
|
```
|
|
|
|
### Description (Required)
|
|
A brief description of the change:
|
|
|
|
- Use imperative mood ("add" not "added" or "adds")
|
|
- Keep it concise (50 characters or less recommended)
|
|
- Don't capitalize the first letter
|
|
- Don't end with a period
|
|
|
|
### Body (Optional)
|
|
Provides more detailed explanation of the change:
|
|
|
|
- Separate from description with a blank line
|
|
- Explain the motivation and contrast with previous behavior
|
|
- Use imperative mood
|
|
|
|
### Footer (Optional)
|
|
Contains metadata about the commit:
|
|
|
|
- **Breaking changes**: Start with `BREAKING CHANGE:`
|
|
- **Issue references**: `Closes #123`, `Fixes #456`
|
|
- **Co-authors**: `Co-authored-by: Name <email>`
|
|
|
|
## Examples
|
|
|
|
### Simple commit
|
|
```
|
|
feat: add user authentication
|
|
```
|
|
|
|
### With scope
|
|
```
|
|
fix(parser): handle edge case in JSON parsing
|
|
```
|
|
|
|
### With body
|
|
```
|
|
feat: add email notifications
|
|
|
|
Users can now receive email notifications for important events.
|
|
This includes account changes, security alerts, and system updates.
|
|
```
|
|
|
|
### With footer
|
|
```
|
|
fix: prevent racing of requests
|
|
|
|
Introduce a request id and a reference to latest request. Dismiss
|
|
incoming responses other than from latest request.
|
|
|
|
Closes #123
|
|
```
|
|
|
|
### Breaking change
|
|
```
|
|
feat!: send an email to the customer when a product is shipped
|
|
|
|
BREAKING CHANGE: The shipping service now requires an email address
|
|
```
|
|
|
|
### Full example
|
|
```
|
|
feat(shopping cart): add ability to remove items
|
|
|
|
Users can now remove items from their shopping cart by clicking
|
|
the remove button next to each item. This improves the user
|
|
experience by allowing corrections without starting over.
|
|
|
|
Closes #456
|
|
Co-authored-by: Jane Doe <jane@example.com>
|
|
```
|
|
|
|
## Common Tools
|
|
|
|
### Commitizen
|
|
Interactive tool for creating conventional commits:
|
|
|
|
```shell
|
|
npm install -g commitizen
|
|
npm install -g cz-conventional-changelog
|
|
echo '{ "path": "cz-conventional-changelog" }' > ~/.czrc
|
|
```
|
|
|
|
Usage:
|
|
```shell
|
|
git cz
|
|
```
|
|
|
|
### Commitlint
|
|
Lints commit messages to ensure they follow conventional format:
|
|
|
|
```shell
|
|
npm install --save-dev @commitlint/config-conventional @commitlint/cli
|
|
```
|
|
|
|
Configuration in `.commitlintrc.json`:
|
|
```json
|
|
{
|
|
"extends": ["@commitlint/config-conventional"]
|
|
}
|
|
```
|
|
|
|
### Husky
|
|
Git hooks to enforce commit message format:
|
|
|
|
```shell
|
|
npm install --save-dev husky
|
|
npx husky add .husky/commit-msg 'npx --no -- commitlint --edit ${1}'
|
|
```
|
|
|
|
### Semantic Release
|
|
Automatically generates releases based on conventional commits:
|
|
|
|
```shell
|
|
npm install --save-dev semantic-release
|
|
```
|
|
|
|
### Conventional Changelog
|
|
Generates changelogs from conventional commits:
|
|
|
|
```shell
|
|
npm install -g conventional-changelog-cli
|
|
conventional-changelog -p angular -i CHANGELOG.md -s
|
|
```
|