- Human-readable sentence case commits format
- Sometimes strict and sometimes loose commit formats
- Not only Monorepo but also single-package repositories
- Release rules are used for semantic analysis of semantic releases to bump versions automatically
- Groups are used to group changelogs
- This also applies to the conventional-changelog ecosystem
The header has a particular format that includes a Type
, a Target
, and a Summary
:
Type(Target): Summary
┊ ┊
┊ └─⫸ Target: Workspace, Package or Role
┊
└─⫸ Type: Bump, Feat, New, Perf, Add, Update, Improve, Fix, Deprecate, Drop, Docs, Upgrade, Revert, Example, Test, Refactor, Chore, Misc
-
Type
- Sentense case only
-
Target
- Sentense case only
- Accept starting with Markdown characters ` * _ # ~
- Can be omitted in one workspace
-
Summary
- Sentense case only
- Accept starting with Markdown characters ` * _ # ~
- No period at the end
Such commits result in version bumps.
Perf
Add
Update
Improve
Fix
Deprecate
Drop
Upgrade
Revert
Bump(Patch)
Docs(README)
Changelog
+0.0.1
A change to a system or product designed to handle a programming bug/glitch.
Fix: <Summary>
Fix(Target): <Summary>
🟢 Good for a monorepo
Fix(CSS): HEX codes were incorrectly parsed as selectors
┊ ┊
┊ └─⫸ A brief description of the specific error
┊
└─⫸ CSS is a workspace package
🔴 Bad for a monorepo
Fix: Fix issues by extracting hex codes with strict rules
┊ ┊ ┊
┊ ┊ └─⫸ Describe the problem rather than the solution
┊ ┊
┊ └─⫸ Don't repeat the word `Fix` in Summary
┊
└─⫸ Without a `(Target)`, the viewer cannot identify the participating workspace
Changelog
+0.0.1
Perf: <Summary>
Perf(Target): <Summary>
Example
Perf: Refresh cache when configuration changes
Changelog
+0.0.1
Add: <Summary>
Add(Target): <Summary>
Example
Add(CSS): Option `.preference` for default theme
Changelog
+0.0.1
Improve: <Summary>
Improve(Target): <Summary>
Example
Improve(Home): Swap the order of **Feature** and **Pricing**
Changelog
+0.0.1
Static content updates such as articles, news, about, profile, etc.
Update: <Summary>
Update(Target): <Summary>
Example
Update(Team): The member's job title changed
Changelog
+0.0.1
Upgrade environment, system, dependencies, etc.
Upgrade: <Summary>
Upgrade(Target): <Summary>
Example
Upgrade(Compiler): Dependency `@master/css@^2.0.0`
Changelog
+0.0.1
Alias: Drop
Deprecate features, options, parameters, units, pages, etc.
Deprecate: <Summary>
Deprecate(Target): <Summary>
Example
Drop(Normal CSS): `--font-mono` `--font-sans` `--font-serif` CSS variables
Changelog
+0.0.1
Revert: "<Reverted Commit Header>"
This reverts commit <Reverted Commit Hash>.
If you are using Git Graph extension for VSCode, Clicking Revert
will automatically generate the following format:
Revert "<Reverted Commit Header>"
This reverts commit <Reverted Commit Hash>.
Example
Revert "Fix(Repo): PeerDependencies -> Dependencies"
This reverts commit 779347237eef77e9137f88095e1fb813e5101c2b.
+0.0.1
The README.md
of the NPM package can only be updated by releasing a new version. At this time, it's very convenient to trigger the patch through:
Docs(README): <Summary>
Docs(README): Features section
It's reasonable to update README.md
by bumping to the patch version because the documentation is part of this version.
+0.0.1
Manually bump a patch version due to special reasons.
Bump(Patch): <Summary>
Example
git commit --allow-empty -m 'Bump(Patch): `+0.0.1`'
Feat
New
Bump(Minor)
Changelog
+0.1.0
Alias: New
Feat: <Summary>
Feat(Target): <Summary>
Example
New(Syntax): A new shorthand `WxH` for `width:` and `height:`
+0.1.0
Manually bump a minor version due to special reasons.
Bump(Minor): <Summary>
Example
git commit --allow-empty -m 'Bump(Minor): `+0.1.0`'
Bumping to the next major version should be triggered manually by the manager rather than relying on a flag in a given commit.
Format
Bump(Major): <Summary>
No clear motivation for <Summary>
yet? Hit Version
or the next version, like v2.0.0
.
🟢 Good for a monorepo
git commit --allow-empty -m 'Bump(Major): Master CSS v2.0'
This is just a commit used to trigger version analysis, don't be obsessed with changes in files, so add --allow-empty
Trivial routine commits include test cases, examples, and environment configurations.
Docs
Tests
Example
Chore
Misc
Docs: <Summary>
Docs(Target): <Summary>
Example
Docs(CSS): Initialize Master CSS with custom configuration
Test: <Summary>
Test(Target): <Summary>
Example
Test(Syntax): Check CSS rules for `WxH` output
Example: <Summary>
Example(Target): <Summary>
Example
Example(Next.js 13): Update to layouts RFC
- Alias:
Chore
or no prefix
Misc: <Summary>
Misc(Target): <Summary>
<Summary>
Example
Chore: Update README.md
I prefer no prefix; having to keep prefixing every frequent trivial item is annoying, and marking trivial items doesn't make much sense.
🟢 Better day-to-day development experience
Update README.md