-
Notifications
You must be signed in to change notification settings - Fork 0
003_Conventional Commits
A Conventional commit is not only a way to format your commit messages but also an ecosystem tool for versioning your software and communicating these changes to the rest of the world.
This specification came from Angular.
It synergies with the concept of semantic versioning by describing respective features, fixes, and breaking changes made in commit messages.
The commit message should be structured as follows:
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
The commit contains the following structural elements, to communicate intent to the consumers of your library:
- fix: a commit of the type fix patches a bug in your codebase (this correlates with PATCH in Semantic Versioning).
- feat: a commit of the type feat introduces a new feature to the codebase (this correlates with MINOR in Semantic Versioning).
- BREAKING CHANGE: a commit that has a footer BREAKING CHANGE:, or appends a ! after the type/scope, introduces a breaking API change (correlating with MAJOR in Semantic Versioning). A BREAKING CHANGE can be part of commits of any type.
- types other than fix: and feat: are allowed, for example @commitlint/config-conventional (based on the the Angular convention) recommends build:, chore:, ci:, docs:, style:, refactor:, perf:, test:, and others.
- footers other than BREAKING CHANGE: may be provided and follow a convention similar to git trailer format.
feat: allow provided config object to extend other configs
BREAKING CHANGE: extends key in config file is now used for extending other config files
feat!: send an email to the customer when a product is shipped
feat(api)!: send an email to the customer when a product is shipped
chore!: drop support for Node 6
BREAKING CHANGE: use JavaScript features not available in Node 6.
docs: correct spelling of CHANGELOG
Commit message with scope feat(lang): add Polish language
Commit message with multi-paragraph body and multiple footers fix: prevent racing of requests
Introduce a request id and a reference to latest request. Dismiss incoming responses other than from latest request.
Remove timeouts which were used to mitigate the racing issue but are obsolete now.
Reviewed-by: Z Refs: #123
Best Practices
Helpful reminders to future selves:
Use the commit message conventions that trigger semantic releases 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 Always leave a comment when creating, reviewing, and merging a pull request
Tooling for Conventional Commits: commitizen/cz-cli: A Node.js tool to create commit messages following the Conventional Commits specs. semantic-release: A tool that automates the whole package release workflow including: determining the next version number, generating the release notes and publishing the package.
Install commitizen:
Making your repo Commitizen friendly
For this example, we'll be setting up our repo to use AngularJS's commit message convention, also known as conventional-changelog.
First, install the Commitizen CLI tools:
npm install commitizen -g
Next, initialize your project to use the cz-conventional-changelog adapter by typing:
commitizen init cz-conventional-changelog --save-dev --save-exact
The above command does three things for you:
Installs the cz-conventional-changelog adapter npm module Saves it to package.json's dependencies or devDependencies Adds the config.commitizen key to the root of your package.json file as shown here: ... "config": { "commitizen": { "path": "cz-conventional-changelog" } }
If your repo is Commitizen friendly:
Simply use git cz or just cz instead of git commit when committing. You can also use git-cz, which is an alias for cz.
When you're working in a Commitizen-friendly repository, you'll be prompted to fill in any required fields, and your commit messages will be formatted according to the standards defined by project maintainers.