Commitizen — Clean & Simple

8 min readFeb 26, 2024

Keep off the hassle of thinking how commits should be formatted

Quick Disclaimer

This article is a reflection of my personal feelings and experiences, viewed solely through my own perspective. As such, the following narrative is shaped by my individual understanding and perception of events. While I aim to convey my experiences authentically, readers should approach the text with the understanding that it represents my subjective viewpoint. Any critics and feedbacks of the article are very welcomed.

Introduction

Developing on an already built system is very easy, the question here is how to build that system. For years that question has been boggling my mind on how would you create a hassle free system where the developers only need to focus on technical stuff like programming without the necessity of thinking how to do this, how to do that, etc that are trivial to the main task. One task that I managed to found an answer to is the git commit message issue. Ever since I developed my first app with a team, one of the early questions that are always asked are how are branches and commits supposed to be formatted. Once that happens, we would probably spend around an hour or two figuring out which format could do us best. This would probably be fine in a long term project, however in a project that is relatively short and has to be maintainable, debating with these kinds of trivial stuff are just a hassle to do. Thus after years of searching and scavenging the internet, I come across this one libary called commitizen.

This image is the symbol of commitizen and for reference and documentation you can find it here

What is commitizen?

Simply put, commitizen is an open-source library that gives out guidance on what you need to write at your commit message when trying to commit your work. It breaks down important parts of a commit message into points and once the user is finished typing it, commitizen immediately formats it so it looks nice and easily readable by other developers. Most importantly it removes the necessity of asking the question “How the commit message is supposed to be written/formatted?”.

How to use commitizen?

To give an example, this is how I used commitizen in my Next Js Project but note that commitizen works with any node based project. You only need Node Package Manager (npm) and git as a prerequisite.

For starters using your terminal change its location to your node based project directory (in my case, my Next Js project), you can use the command

$cd path/to/project/directory

Once you have done that you can immediately run the following command to add commitizen to your application

$npm install -g commitizen

Once that command is done, you can try adding some changes to your project and then in order to use commitizen run the following commands

$git add .
$npm cz

Now you will see that commitizen will start asking you questions that are going to structure your commit message such as

The image above is the example of the options available in commitizen. The options mainly consists of what type of change, what are the scope of the change, short description, long description, does it affect any open issues, and does it contain breaking changes.

Once you finish answering all of those questions, you can now push your commit to your repository using the command

$git push remote_name branch_name

Next you can finally see your commitizen message in your repository for example

The image above is the example of one of my commits using commitizen in my project. As can be seen commitizen automatically formats the commit message without me having to remember everytime how to format or what is the standard commit used in my team.

Commit of the image: https://gitlab.cs.ui.ac.id/maams-ppl/maams-fe/-/merge_requests/5

Get Nicholas Sidharta’s stories in your inbox

Join Medium for free to get updates from this writer.

Remember me for faster sign in

For further information and special cases you can refer to commitizen’s documentation here

What can you add on top of this?

Commitizen is only one of the tools that helps your team create a more efficient working environment. On top of it you still have to discuss branching name systems, merge request rules, etc. As a rule of thumb, it is best for a team working environment to use merge request to handle the pararel workflow, since its a good way of keeping track of good quality code and assure that production wouldn’t just immediately fail since someone pushed a code immediately to the production branch.

This is what happens when you don’t protect your master/main branch

Thus its better for you and your team to protect the production branch, collect development in the staging branch, and only let pushes to newly created branches and only way to push changes to either staging or production is through creating a merge request that must be approved by a minimum of 1 or more person depending on your team size.

Another important detail if you’re working on a team, keeping track of tasks that have been assigned could be difficult if you don’t put it somewhere thus the necessity of using tools such as scrum boards are important to keep track and make sure the task is completed. Not only that using scrum boards could also help you and your team to know how far or on what status is that part of the project is in (i.e todo, in progress, in review, merged/completed, etc). Some examples of scrum boards one might use are:

These are some popular 3rd party tools that have the feature of scrum boards specifically. Each have their own advantages and disadvantages but use on whichever suits your team the best.

In my case, my team uses Linear to track our progress. Here are some examples of tickets and issues made using linear.

The image above is the list of issues that are located inside of an epic. Epic is a term used in project management and software development to describe a large body of work that can be broken down into smaller tasks or stories. In an agile framework, an epic is a significant deliverable that encompasses multiple related issues or user stories. These issues or stories represent specific pieces of functionality or features that contribute to the completion of the epic. This hierarchical structure facilitates prioritization, assignment, and status tracking, enabling a more streamlined and collaborative workflow.

This image depicts when a ticket is clicked, the requirement and description of said ticket is mainly stored in this detailed page. The top section mainly is the title, followed by a section for the ticket description, it can either be short and simple for minor task but long and detailed for larger tickets. There also an option to create child issues so when a task is still too big for a ticket, there is the option to break it down to smaller tasks. Finally the bottom part is for checking the logs for ticket updates and changes, as well as comments to support communication between developers and teams.

Available Statuses, Estimates, and Assignee

This image shows the fields available in a ticket in linear. For ticket statuses, linear gave us these by default where:

Todo means that the ticket has been assigned and should be done within this sprint but hasn’t been started by the developer
In Progress as in the name, the developer has started to work on this ticket but still not done with the ticket
In Review means that the developer assigned to this ticket has created a pull request in the remote repository and is waiting for a senior engineer or another team member to code review the pull request.
Done as in the name is a status to show when a ticket is done in the past or a developer has managed to merge the code into the collective branch where safe pull requests has been merged.
Cancelled means that the ticket has been cancelled mid development and will not be continued in development.
Duplicate means that there is another ticket that has the same task as this ticket thus one of them will be cancelled since there is already another one covering it.

This image shows one of linear’s feature that is to list all my available issues. As a developer trying to find a ticket without a search or filter would be hell since in a big scale project the tickets could be in the number of hundreds or even thousands of past tickets. Thus linear made it way more easier by giving us the quick access on the sidebar to see your tickets whether it is done or on-going, all of your tickets (the tickets that have your name as an assignee) will be shown in this page.

This image depicts the feature of roadmaps in linear to see all available epics of my project. As can be seen in my project there are mainly 4 epics that describe the core features of the project such as Authentication, Validator, Landing Page, and History. These groups are very useful in organizing and finding which ticket is located in which core feature that is trying to be developed.

The image above depicts an tickets with subtasks, which means that the issue of MAA-17 in the image is a parent ticket of some other tickets, in this case MAAMS Introduction FE issue is a task that includes making a Navbar, Footer, Layout, Landing page header, Creating analysis from landing page, and an FAQ section.

Conclusion

Commitizen is a tool for improving commit message quality and removing the hassle of reminding your team to always use what kind of format that suits best. Aside from Commitizen there is still a bunch of other tools available on the internet that also can be used to increase you and your team’s productivity further let it be a 3rd party app/software or an open source project such as Commitizen. Always be on the look out for those since it might just make your development experience slightly better.