Convetional Commits For Your Commit Message

The Conventional Commits specification is a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history; which makes it easier to write automated tools on top of. This convention dovetails with SemVer, by describing the features, fixes, and breaking changes made in commit messages.

From https://www.conventionalcommits.org/en/v1.0.0/

What's this?

This is a convention for creating commit messages, so other poeple can understand what's happening. Read it in the page.

My TLDR

So basically, Use fix for bumping your PATCH version, and use feat for MINOR version: when we have a new feature.

When We do breaking changes, It should count as a version change, and we use ! for that, While also change our MAJOR version. Example:

1feat!: replace this thing with that thing

There are other types of commit types: build:, chore:, ci:, docs:, style:, refactor:, perf:, test:.

I think, those changes were not meant to make changes to end product. Or is it? I see some people gives example on using chore: when releasing their package. I still don't know much about this.

Ok, from https://gist.github.com/qoomon/5dfcdf8eec66a051ecd85625518cfd13.

Types

• API relevant changes
  • feat Commits, that adds or remove a new feature
  • fix Commits, that fixes a bug
• refactor Commits, that rewrite/restructure your code, however does not change any API behaviour
  • perf Commits are special refactor commits, that improve performance
• style Commits, that do not affect the meaning (white-space, formatting, missing semi-colons, etc)
• test Commits, that add missing tests or correcting existing tests
• docs Commits, that affect documentation only
• build Commits, that affect build components like build tool, ci pipeline, dependencies, project version, ...
• ops Commits, that affect operational components like infrastructure, deployment, backup, recovery, ...
• chore Miscellaneous commits e.g. modifying .gitignore

So i guess, the commit prefix doesn't mean you have to push. You push when you need to push.

Tools: GitHub CI

For Github, I found ReleaseMe to do the job. This will release your package to Github:

.github/workflows/release.yml
.github/release.yml
1name: Github Release
2
3on:
4  push:
5    branches:
6      - main
7
8jobs:
9  create-release:
10    permissions:
11      contents: write
12    runs-on: ubuntu-latest
13    steps:
14      - uses: actions/checkout@v4
15
16      - name: Read package.json
17        uses: krstphrrr/package-json-version-reader@v1.0.0
18        id: package-version
19
20      - name: Create a Release
21        uses: dev-build-deploy/release-me@v0
22        id: release
23        with:
24          token: ${{ secrets.GITHUB_TOKEN }}
25          prefix: v
26          config: .github/release.yml
27          version: v${{ steps.package-version.outputs.version }}

Tools: Local

For enforcing your commits to adhere to this specs, use commitlint. This works with Husky:

1# install commitlint and husky
2npm install --save-dev husky @commitlint/{cli,config-conventional}
3
4# add commitlint config
5echo "export default { extends: ['@commitlint/config-conventional'] };" > commitlint.config.mjs
6
7# initiate husky
8npx husky init
9
10# add commitlint to husky, 
11# trigerring the linter on new commits
12echo "npm run commitlint \${1}" > .husky/commit-msg

lastly, add commitlint to your package.json:

package.json
1{
2  "scripts": {
3    "commitlint": "commitlint --edit"
4  }
5}

Running this locally, i got:

1git add -A; git commit -am 'asdf: asdf'
2
3> next-doc@0.0.3 commitlint /Users/juji/play/next-doc
4> commitlint --edit ".git/COMMIT_EDITMSG"
5
6⧗   input: asdf: asdf
7✖   type must be one of [build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test] [type-enum]
8
9✖   found 1 problems, 0 warnings
10ⓘ   Get help: https://github.com/conventional-changelog/commitlint/#what-is-commitlint
11
12 ELIFECYCLE  Command failed with exit code 1.
13husky - commit-msg script failed (code 1)

Nice, it prevents me from using arbitrary commit message. This is a good tool for a single developer like me, or probably for a team.

Checkout the types of commit it allows:

1[build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test]

... probably will update later