My first Open Source Contribution and how to write better GIT commits

spotnick — Fri, 04 Feb 2022 07:11:51 +0000

Hey guys!

The Problem

I recently stumbled upon this blog post on freecodecamp. We had a discussion in our small team that we need to enforce to write better git commits. Well I assume everybody has that need. How often do ask yourself: "what the heck did I commit there?" and you find yourself digging through the changes and searching for the thing you were looking for. At least I was....

Write better git commits

Writing good git commits is actually not that hard. We decided to go with the angular guidelines here.

In short a git commit should have the following ( I copied the content from the page linked above because there is no need to reinvent what is actually good)

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

Header

The header is mandatory and the scope of the header is optional.

Any line of the commit message cannot be longer than 100 characters! This allows the message to be easier to read on GitHub as well as in various git tools.

Revert

If the commit reverts a previous commit, it should begin with revert: , followed by the header of the reverted commit. In the body it should say: This reverts commit ., where the hash is the SHA of the commit being reverted.

Type

Must be one of the following:

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

Scope

The scope could be anything specifying place of the commit change. For example $location, $browser, $compile, $rootScope, ngHref, ngClick, ngView, etc...

You can use * when the change affects more than a single scope.

Subject

The subject contains succinct description of the change:

use the imperative, present tense: "change" not "changed" nor "changes"
don't capitalize first letter
no dot (.) at the end

Body

Just as in the subject, use the imperative, present tense: "change" not "changed" nor "changes". The body should include the motivation for the change and contrast this with previous behavior.

Footer

The footer should contain any information about Breaking Changes and is also the place to reference GitHub issues that this commit closes.

Breaking Changes should start with the word BREAKING CHANGE: with a space or two newlines. The rest of the commit message is then used for this.

A detailed explanation can be found in this document.

How to do it?

Alright. Having committed to that standard, we were looking for a plugin to handle that for us. I was searching around for good VSCode plugins to handle the commit pattern for us and I found this git-commit-plugin. Sadly it was only in Chinese and that's were my first open source contribution began.

The Issue

First I opened an issue (more a feature request) on Github and asked about a translation in english. (yes I know there is a typo in the title... I was too excited and nervous).

(link to the issue)[https://github.com/RedJue/git-commit-plugin/issues/59#event-5879234299]

After writing with the author if he might accept PRs my journey really began. I was wondering how to implement it, failed and tried again.

The solution and the merge

To add the localization for the plugin depending on the display language configured in VSCode I used the NPM vscode-nls-i18n which provides exactly what I needed. It chooses the right resource files depending on the configured language and if the language is not present it uses english as a fallback. BAM! I had to add resource files for Chinese and English langauge (thanks to deepl.com for the translation...) and had to rewrite some parts of the original code. After some testing and troubleshooting the plugin worked as expected, I did some cleanup and pushed it in my forked branch.
The author was ok with my changes, merged it and published it to the marketplace.

So if you want to use it feel free to write better git commits. :-)

DEV Community: spotnick