Consider: If you had to make a code submission specification (Git tools), what would you do?

Overlooked details

Code submission information is a very small detail in the development, because it does not have any impact on the operation of the code itself, and its main function is to facilitate the search and rollback of the code, so it is easy to be ignored by developers. However, like project documentation and comments, it is essential for high-quality projects. Good submission information not only helps developers find the code for the specified version quickly, but also shows the habits and awareness of developers.

This article wants to talk about this small detail and the training of software engineers (hereinafter referred to as engineers), perhaps for those who are just starting out in the workplace or in the bottleneck of career progression some inspiration.

The code submission information in our current project is messy, so it is necessary to establish a code submission specification.

Here’s a look at how three different engineers deal with self-cultivation at work.

General engineer

Unless you’ve done something like this before, the first thing you do when you’re asked to do a job is open your browser and search for a keyword like “Code submission specification.” You’ll find a lot of results. Through some sorting, the following information is obtained:

Format submission information

<type> (the < scope >) : < subject > / / short line < body > / / short line < footer >type: Submission type. Possible values are as follows: * work: under development (workinProgress) * feature: new feature * fix: bug * doc: documentation changes * style: * Refactor: Modify code but not feature *test: Add tests (testCode) * chore: Changes to the build process or chore (changes don't modify SRC and test files, only config or tasks) scope specifies the scope of the commit impact, such as the data layer, control layer, view layer, etc., depending on the project. Subject: Short description of the commit destination. Footer: describes special cases, incompatible changes, and issue closure.Copy the code

Tools to write submission information

Like Commitizen, the basic operation is as follows:

Install the command line tool
npm install -g commitizen

# install dependencies
commitizen init cz-conventional-changelog --save --save-exact

# submit by extension command
git add .
git cz
Copy the code

Document the above formatting, then install dependencies in your project to try the following, and the job is done

Think further

But this is just the standard of ordinary engineers, how should a good engineer think?

The difference between a good engineer and an average engineer is that they reflect on their work and take the initiative to improve. This means not just being satisfied with getting things done, but taking the initiative to get things done. There are basically two ways to get things done:

  1. Everyone else can do it, but you do it differently.
  2. You can do what others can’t.

Obviously having a submission specification falls into the first category, so good engineers think about it further.

Excellent Engineer

Is there anything that can be improved on the current scheme?

Writing format

There’s a lot of writing to do with each submission, and if submitting a piece of code each time is like writing a short essay, it’s going to be annoying. This is like driving to work in less than half an hour, but now the requirement of low-carbon travel can only take an hour by bike, this kind of regulation is not feasible. So simplify:

  1. When the file path is long or the number of files is large, the scope becomes very long, affecting the view of the subject. The name of the modified file (folder) can also be found when the specific commit record is queried. Even more troublesome is that if you omit or make a mistake when submitting it, it will backfire, so omit.
  2. The body and footer are both part of the detailed description of the submission, merged into optional description.

Submission tool

The git cz command can replace the git commit command to commit code, but if the engineer does not use git cz and still uses git commit command to commit code, the verification will be invalid. So we need a validation tool to ensure that our specification works, and Git already has hooks for us. Hooks are similar to the life cycle of a Web component and can trigger the corresponding shell script before and after some operation. Git commit contains four hooks, in order:

  • The pre – commit. Triggered before submission, does not receive parameters, can perform some file verification work.
  • Prepare – commit – MSG. A pre-commit trigger that receives message parameters and is used to append something before committing.
  • Commit – MSG. Triggered before submission, can receive message parameters, used to check whether the submission message complies with the specification.
  • Post – commit. Triggered after submission, automatic push, code deployment and other operations can be performed.

Here we select commit-msg and the script will look something like this:

#! /bin/sh
if grep -Eq "^(work|feature|fix|refactor|doc|test|chore|style|revert):\s*\w+" "The $1"; then
  exit 0
else
  echo "Please format your commit message as follow:"
  echo "<type>:<title>"
  echo "<description>(optional)"
  exit 1
fi
Copy the code

Is there anything that can be added to the current plan?

The norm

Norms are like systems. A good system needs not only the designer to design, but also the executor to know and cooperate. So another thing to think about once you have documentation and tools is promotion within the team. The commonly used methods of promotion include making a PPT for meeting and training, or putting the information on the team wiki to remind everyone to check, but I will not elaborate here.

In a further step

At this point, the task is not only done, it is done. But to maximize personal advancement, it’s not enough to be good. You have to be great. So in addition to getting things done, think about maximizing value.

Outstanding Engineer

Going back to the example, is this solution possible for other teams/scenarios?

generality

The formatting part is basically fine, but the submission tool can be a big hurdle. Node.js is usually just a tool for the front-end team. If you want to promote the use in other teams, not only the learning cost, but also the introduction of additional dependencies in the project, which is not strong operability.

Does that mean finding solutions for projects in other development languages? This is certainly possible but not necessarily the best way, because the time cost is too high, and the best way is to find a universal solution.

Or hook

In fact, git has already provided this scheme for us, or used before the hook. While Node.js modules such as Commitizen are not cross-language solutions, their step-by-step prompts, followed by user input, work well for those unfamiliar with the specification. So we can use this form in the hook script.

For developers who are familiar with the specification, however, they may want to use git commit to commit once and for all. Therefore, some verification is added — interactive prompts are provided for non-compliant commits, and developers are guided through the steps to complete the commit. Because the script content is long, it will not be posted here, interested readers can go to the warehouse address at the end of the article.

perfect

If you want to do a better job, you can use the Template function provided by Git. For details, see the repository address provided at the end of this article.

conclusion

The working attitude determines the potential of an engineer, while the thinking dimension determines the ceiling of an engineer’s ability (of course, this sentence may also be applicable to other positions).

It was a small undertaking to develop a submission specification, but we can summarize the differences between engineers at different levels in these two areas:

General engineer Excellent Engineer Outstanding Engineer
Work attitude Do what the company arranges, learn what, lack of initiative consciousness. I can finish the tasks assigned by the company, sometimes more than expected. At the same time, I use time to learn after work. Not only does he often exceed expectations to complete the company’s tasks, but he also takes the initiative to think about existing problems or areas that could be improved by the team and product and assigns tasks to himself
Thinking dimension Simple, punctate. Focus only on the task, how do you get it done Linear, longitudinal. Think about the goals behind tasks and how you can better achieve them rather than just complete them Mesh, global. Switch identity thinking to maximize the value of task outcomes to the organization

If you found this article helpful, please give it a thumbs up. Thanks for reading

Reference article:

  • Git Commit Trigger hook
  • Commit Message and Change Log Writing Guide

Submit specification warehouse address: github.com/yalishizhud…

My new bookThe Amazing JavaScript Engineer: Advanced Progression from front End to Full EndIt has been put on the shelves, and has been recommended by many technical experts such as Teacher Ruan Yifeng. I hope to help more front-end engineers grow and improve together, have comprehensive ability and global vision, and become great JavaScript engineers!