mirror of
https://github.com/sharevb/it-tools.git
synced 2026-11-20 21:23:08 +03:00
1 parent
bae6175c4b
commit
19d494fbb3
1 file changed
+154
-25
@@ -1,34 +1,163 @@
|
||||
# Semantic Commit Messages
|
||||
# Conventional Commits Cheatsheet
|
||||
|
||||
See how a minor change to your commit message style can make you a better programmer.
|
||||
## Structure
|
||||
|
||||
Format: `<type>(<scope>): <subject>`
|
||||
|
||||
`<scope>` is optional
|
||||
|
||||
## Example
|
||||
A conventional commit message follows this structure:
|
||||
|
||||
```
|
||||
feat: add hat wobble
|
||||
^--^ ^------------^
|
||||
| |
|
||||
| +-> Summary in present tense.
|
||||
|
|
||||
+-------> Type: chore, docs, feat, fix, refactor, style, or test.
|
||||
<type>[optional scope]: <description>
|
||||
|
||||
[optional body]
|
||||
|
||||
[optional footer(s)]
|
||||
```
|
||||
|
||||
More Examples:
|
||||
## Elements
|
||||
|
||||
- `feat`: (new feature for the user, not a new feature for build script)
|
||||
- `fix`: (bug fix for the user, not a fix to a build script)
|
||||
- `docs`: (changes to the documentation)
|
||||
- `style`: (formatting, missing semi colons, etc; no production code change)
|
||||
- `refactor`: (refactoring production code, eg. renaming a variable)
|
||||
- `test`: (adding missing tests, refactoring tests; no production code change)
|
||||
- `chore`: (updating grunt tasks etc; no production code change)
|
||||
### Type (Required)
|
||||
The type describes the kind of change being made. Common types include:
|
||||
|
||||
References:
|
||||
- **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
|
||||
|
||||
- https://www.conventionalcommits.org/
|
||||
- https://seesparkbox.com/foundry/semantic_commit_messages
|
||||
- http://karma-runner.github.io/1.0/dev/git-commit-msg.html
|
||||
### 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
|
||||
```
|
||||
Reference in new issue
Block a user