Please stop writing bad submission messages!

Time:2021-1-24

I think we all have this experience

You are developing a project that uses git for version control.

You’ve just made changes and want to update the branch quickly.

So, you open the terminal and update the remote branch with the changes you make through some quick commands.

git add .
git commit -m "added new feature"
git push

But then you did some tests and found a bug in your code.

Don’t worry, you can quickly find a solution and submit again to solve the problem.

git add .
git commit -m "fix bug"
git push

You repeat this process several times, and now you finally get a git commit log, as follows:

Please stop writing bad submission messages!

At the moment, this seems good for you. After all, you are currently working on that part of the code, and even if the submitted information does not convey your intention to change, you can easily explain what has been done.

problem

A few months have passed, and now another developer is reviewing your changes.

They try to understand the details of your changes, but they can’t get any information because the message you submitted is not descriptive.

Then, they try to see the difference for each submission. But even if they do, they’re still unsure of the thinking process behind your choices in implementation.

So they can use itgit blameFind out who made the changes and start asking you about the implementation.

However, as time has passed for a long time, so you will not remember too much. You check by submitting, and you no longer remember the logic behind the implementation decisions in the project.

Finally, you send your colleagues sad emoticons on wechat and tell them that you can’t provide more information than they know.

Write good submission

I hope the above situation has made you understand why to write wellgit commitThe news is important.

In team development, we have to make it easy for other collaborators to understand what we do.

Ideally, a good submission message would be divided into three parts: subject, body, and end.

theme

The topic should be a concise line summarizing the changes you submitted.

Here is a good example of submission information, such as “feature: query item application rate function”.

A wrong submission message, such as “fix bug”, will be lost when others see it.

text

The text contains the information you want to convey, where you can learn more about the changes. Please note that for small submissions, such as correcting typos, you may not need the text, because the subject line should be informative enough.

In the text, you should have an in-depth understanding of the changes in progress and explain the causes and consequences of the actions being performed.

You can explain why these changes were made, why you chose to implement them in this particular way, and any other reason that can help people understand the thinking process behind your submission.

Try not to repeat the obvious things in the comparison code. Instead of explaining your changes line by line, focus on covering more advanced details that may not be obvious from reading the code. The ultimate goal is to provide context for the development process around this change, which is mainly about its cause and goal.

ending

You can write useful metadata about the submission in the last line, such as JIRA ticket number, author name and additional links.

This helps to connect important information about your change.

summary

What are you waiting for? Waiting to be beaten up by colleagues? Don’t start following the best practices for git to submit messages!