How Can We Standardize Git Commits?
By: Alibaba Cloud
Tags: Git, Alibabacloud, Computing, App Development, Developer

By Ruiguang

Have you ever encountered an annoying git commit during team development? How can we write commit messages more clearly to avoid similar problems? In this article, we will discuss practices for standardizing git commits, define a format for commit messages, and monitor commits through webhooks to avoid non-compliant code commits.

Background

Git users need to write commit messages each time they commit code, otherwise, the commit is not allowed. Generally, the commit message should clearly specify the purpose of the commit and its operations. However, in daily development, we encounter commit messages that contain all sorts of strange things, such as mixed Chinese and English texts and general descriptions of bug fixes. Sometimes, developers do not seem to know what bugs they are fixing. This makes code maintenance very difficult. Therefore, we want to monitor git commit messages in some way to ensure higher quality and greater development efficiency.

Specifications

In the early days, we searched through huge amounts of data about git commit specifications on the Internet, only to find that the Angular specification is the most widely used writing method. Reasonable and systematic, it also has supporting tools (IDEA has plug-ins to support this writing method). Finally, we summarized a set of git commit specifications based on the existing specifications of the AMAP department.

Format of Commit Message

<type>(<scope>): <subject>

Type (required)

This indicates the type of the git commit. Only the following types are allowed:

feat : Introduces a new feature.

: Introduces a new feature. fix/to : Fixes a bug found by QA or developers.

: Fixes a bug found by QA or developers. fix : Generates diff and automatically fixes a bug. This is used to fix bugs with a single commit.

: Generates diff and automatically fixes a bug. This is used to fix bugs with a single commit. to : Only generates a diff instead of automatically fixing the bug. This is used for multiple commits. Then, you can use fix for the commit when you finally fix the bug.

: Only generates a diff instead of automatically fixing the bug. This is used for multiple commits. Then, you can use fix for the commit when you finally fix the bug. docs : Commits documentation only changes.

: Commits documentation only changes. style : Commits format changes that do not affect code running.

: Commits format changes that do not affect code running. refactor : Commits a code change that neither fixes a bug nor adds a feature.

: Commits a code change that neither fixes a bug nor adds a feature. perf : Commits optimization changes, such as to improve performance and experience.

: Commits optimization changes, such as to improve performance and experience. test : Adds tests.

: Adds tests. chore : Commits changes to the build process or supporting tools.

: Commits changes to the build process or supporting tools. revert : Rolls back to the previous version.

: Rolls back to the previous version. merge : Merges code.

: Merges code. sync : Synchronizes bugs of the main thread or a branch.

Scope (optional)

Scope is used to describe the scope of the impact of a commit, such as the data layer, control layer, or view layer, depending on the project.

For example, in Angular, it can be location, browser, compile, rootScope, ngHref, ngClick, or ngView. If your modification affects more than one scope, you can use * instead.

Subject (required)

The subject is a brief description of the purpose of a commit. It can be up to 50 characters in length. Do not end with a period or other punctuation marks.

Therefore, the git commit message will be in the following formats:

Fix(DAO): User query missing the username attribute

feat(Controller): Development of user query interfaces

The above message shows the git commit specifications we have formulated. So, what are the benefits of standardizing git commits?

First, it is convenient for programmers to trace the commit history to find out what happened. Second, once the commit message is specified, we will take the commit seriously and no longer put all kinds of changes in a git commit. In this way, the history of code changes will be clearer. Third, the formatted commit message can be used to automatically output the change log.

Monitoring Service

Usually, after we propose a specification, we would share its advantages and benefits for better implementation. If everyone agrees with it, it is best to take some mandatory measures. The same is true of the git commit specification. After we shared the specification, we considered mandatory checking at the source. Then, only commit messages that conform to the specification can be submitted. However, due to the operation permission issues of the code repository, we finally chose to use webhooks to urge everyone to commit codes based on the specification by sending warnings. In addition to monitoring the git commit message specification, we also monitor the committing of a large amount of code and the deletion of files to reduce accidental operations.

Overall Process

Service registration: adds relevant data to the code repository.

adds relevant data to the code repository. Duplicate check: prevents merge requests from being verified again.

prevents merge requests from being verified again. Message alerts: sends alert notifications for non-compliant operations, commits for a large amount of code, and deletion of files.

sends alert notifications for non-compliant operations, commits for a large amount of code, and deletion of files. DB: stores project information and git commit information to facilitate subsequent statistics on the rate of compliant commit messages.

The webhook works on the code repository. When you submit a git commit to the repository, the webhook is triggered. Then, the webhook obtains the commit message from the commit to verify whether the message conforms to the git commit specification. If not, it will send an alert message. If the commit is in the correct format, the webhook will call the GitLab API to obtain the commit diff and verify the amount of code to be committed and whether any files are renamed or deleted. If a large amount of code is committed or files are operated on, it will send an alert and save all entries to the repository.

Alert messages are sent to the corresponding DingTalk group in the following formats.

We also compile statistics on total git commits, the number of commits for each user, and the number and rate of non-compliant commits, as shown in the following figure.

Thinking About the Future

Git hooks include client-side hooks and server-side hooks. Client-side hooks can be divided into the pre-commit hooks, prepare-commit-msg hooks, commit-msg hooks, and post-commit hooks. They are mainly used to control the client-side git commit workflow. You can configure hooks for use in the .git directory of the project root directory, or configure a global git template for all git projects on your PC. Server-side hooks are divided into the pre-receive hooks, post-receive hooks, and update hooks. They are called when the server receives commit objects.

The webhooks used to monitor git commits are server-side hooks, which are equivalent to post-receive hooks. This method does not prevent the code commit. It only sends alerts to constrain user behavior. However, non-compliant commit messages are still submitted to the server, affecting the subsequent generation of change logs. Due to permissions issues of the code repository, we can only add post-receive webhooks. If you have higher permissions for the code repository, you can use server-side pre-receive webhooks to reject non-compliant git commit messages. As long as the git commits conform to specified, we can even associate codes with bugs and requirements.

Of course, we can also consider using client-side pre-commit hooks. After git adds commits, we can execute the pre-commit hook during the execution of the git commit. When the script execution is correct, the commit process continues. Otherwise, the commit is rejected. Client-side git hooks are located in the hooks folder in the hidden file .git under each git project. We can modify the configuration file to add our rule check to prevent the commit of non-compliant messages. We can also intercept them at the source through client-side commit-msg hooks. Modifying the hooks file in the .git directory under each git project seems like a waste of time. In fact, we can configure a global git template to achieve the same result. However, this involves the synchronization of the hooks configuration file on the local machine. We need to synchronize the changes to the configuration file to the relevant projects. Therefore, you need to make a choice between client-side hooks and the server-side hooks based on your actual needs.

In addition to specification restrictions, git hooks can also be used for many other things. A git commit provides a large amount of information about the author, code repository, and commit. Our monitoring service compiles statistics on git commits based on the author information. In this way, it can monitor conformance with the commit message specification and other aspects of our work. We can also associate git commits with bugs. Then, when we look at the bug, we can view the code changes that solved the bug, which is very helpful for tracking problems. Of course, we can also associate git commits with related requirements in the same way. For example, we can define a format of feat * 786990 (ID of the requirement) and then commit codes in this format upon git commits. Finally, webhooks can associate the requirements with git commits based on this format. They can also be used to trace the amount of code for a certain requirement. Of course, this example is not necessarily appropriate, but it is enough to prove that the powerful functions of git hooks are of great help in process specifications.

Summary

Coding specifications and process specifications are crucial in the software development process as they can greatly facilitate the process. The same is true of the git commit specification, which is necessary and requires little effort and time. With it, we can troubleshoot problems more efficiently. As programmers, we should pay more attention to the standardization of code and processes and never compromise on quality.

Original Source: