diff --git a/src/tools/git-semantic-commit-memo/git-sem.memo.md b/src/tools/git-semantic-commit-memo/git-sem.memo.md index 40071693..9131d4c9 100644 --- a/src/tools/git-semantic-commit-memo/git-sem.memo.md +++ b/src/tools/git-semantic-commit-memo/git-sem.memo.md @@ -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: `(): ` - -`` 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. +[optional scope]: + +[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 \ No newline at end of file +### 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 ` + +## 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 +``` + +## 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 +``` \ No newline at end of file