Conventional Commits or how to improve the reliability of your commits

One of my good intentions of 2020 is to improve my documentation skills in my projects or where I contribute.

Since 2019 I am one of the maintainers of VVV and one of the first tasks that I chose to do was to close all the ticket about documentation stuff, 10 tickets where I did overall 43 commits.

This because the project for newcomers can difficult and as workshop about the usage of this tool I said that it was the case to do something about it.

The first thing that I learned over the fact that my English can be *bleah* that the reviewers of documentation has a lot of patience to check if everything is clear and if the fact can be explained better (Thanks Tom).

After this experience I chose to revamp the wiki stuff of WordPress Plugin Boilerplate Powered with a new page and new content. I read the Google documentation style guide as first step and get an idea about how the content, the various steps and how to reorganize the few pages that I already have.

Also after the experience of my first book I had few ideas about how to simplify the structure. I studied a bit also other documentation webiste that I like, as example the WP-Browser website.
Maybe copy that documentation is too much as first step but is important to have an idea about the final goal.

Anyway when I started on documenting myself about how to write better (or fight my will) I was thinking that Merge commits in the pull request view of GitHub was nice. After all I can get all my commits named like “fix” (and you are one of them that do that) to get merged with the pr title.

Also, I am a big fan of CommitStrip and I think that there is a commitstrip’s strip for any dev/sysadmin issue like this or this.

So on my searching I discovered the Conventional Commits project:

A specification for adding human and machine readable meaning to commit messages

The point is to have commits that can be parsed from another tool, as example they are following a specific standard, they start with a category:

build|ci|docs|feat|fix|perf|refactor|style|test|revert

Followed by a subcategory inside parenthesis and a colon, the rest is for the commit message itself. The official website include some exception and more information about the standard with also other tools.

I looked for the various tools that can validate my commit messages automatically, so I will be forced to follow this rules or I cannot work.

Hard ideas require hard measures [fake quote]

After trying various tools I found a tiny python script that can validate and do the commit for me, but I lost the original source of that… sorry.

In conclusion a new alias for my git workflow that I used on my first project from start just to test it. Now I want to use it on old projects to change the workflow in all my repository, I waited for a new project just to see if it is so blocking but it isn’t.

Leave a Reply

Your email address will not be published. Required fields are marked *

Conventional Commits or how to improve the reliability of your commits

time to read: 2 min
0