Writing in the front

As a developer, variable names and commit messages can sometimes be a headache. This article will focus on how to write a commit Message elegantly.

What’s the weirdest code submission you’ve ever seen?

On a project at my last company, I saw the weirdest code submission I’ve ever seen, and it still sticks in my mind. The first three commit records for that project are:

First Blood

Double kill

Triple kill
Copy the code

It’s so funny, I wonder if that guy is hacking while writing code. Have you ever seen a weird commit message? !

Not only does such submission fail to inform others of what was previously submitted, it also makes them feel unserious and unprofessional.

What benefits do commitmessages of specifications provide?

The benefits of standardizing commit Messages

  1. It is readable and can be used to determine the change content and impact scope of the commit

  2. You can filter out unwanted submissions based on different types of submissions to improve efficiency

  3. ChangeLog can be automatically generated, and even the version of semantic language can be automatically updated

  4. Codereview communication costs can be reduced

  5. A clear and standard Commit messge can help you behave professionally

So what is a good Commit message? Let’s take a look at two submission styles that are widely accepted in the industry.

Presents the specification

The Angular COMMIT message consists of a title, body, and footer, each separated by a blank line. The heading section includes three parts: type, scope and topic.

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

Type Submission type

The submission type must be one of the following:

Feat: Added a new feature

Fix: Fixes bugs

Docs: Only the document is modified

Style: Changes made that do not affect the meaning of the code, whitespace, formatting, missing semicolons, etc

Refactor: Code refactoring, neither bug fixes nor new feature changes

Perf: Code that improves performance

Test: Adds a test or updates an existing test

Chore: Updates to build or assist tools or dependency libraries

The scope ranges

Specifies the scope that the currently committed code affects, or use * if the current change affects more than one scope

The subject description

Include concise descriptions of changes: use imperative sentences, present tense :”change” instead of “changed” or “changes”, do not capitalize the first letter, and do not end with a dot (.)

Body text

Using imperative sentences, the body should include why and what was changed.

Footer Footer comment

Used to place Breaking Changes or Closed Issues

But these Commits specification

A specification derived from Angular’s submission specification is largely based on its Augular submission format

<type>[optional scope]: <description>
[optional body]
[optional footer]
Copy the code

Type Submission type

The type must be provided and must be a noun followed by an optional scoped field and a necessary colon and space;

  • You must use the feat type to submit a new feature.
  • When fixing a bug, you must use the fix type;
  • You can use types other than feat and fix;

The scope ranges

The scope must be a noun that describes a part of the code and uses parentheses

The description described

The description is required, and the field must follow the type/scope space. A description is a short summary of the code change

Body text

The body is selected if the writing must begin after a blank line at the end of the description field

footer

After a blank line at the end of the text, one or more lines of footnotes can be written

BREAKING CHANGE

Incompatible updates must be marked at the beginning of the body area, or the beginning of a line in the footnote area, and must contain the text BREAKING CHANGE in uppercase, followed by a colon and a space.

A description must be provided after BREAKING CHANGE: to describe the changes to the API. For example, BREAKING CHANGE: Environment variables now take precedence over config files.

You can append! After the type/scope prefix and before:. Character to further alert to incompatible changes. When you have! For the prefix, the text or footnote must contain BREAKING CHANGE: Description

Conventional Commits agree with the SemVer specification.

SemVer is a set of semantic versioning conventions defined in the format ** X.Y.Z (major version number). Revision No.) ** :

X. Major version: Specifies the major version number to be incremented if the changes are not backward compatible

Y. Minor version: Added functions or modified for backward compatibility

Z. Revision number: Made a backward compatibility fix

Conventional Commits are in line with SemVer norms for what purpose? ! We can automatically generate semantic versions based on the type of commit.

We’re familiar with The Electron project, which has adopted the Specification Conventional Commits. Other open source projects that have adopted the specification are

  • Yargs: popular command-line argument parser.
  • Istanbuljs: A set of open source tools and libraries that generate test coverage for JavaScript tests.
  • Uportal-home and uportal-application-Framework: used to enhance the optional user interface of Apereo uPortal.
  • Massive. Js: A data access library for Node and PostgreSQL.
  • Scroll Utility: an example of a scroll utility for centered elements and smooth animation.
  • Blaze UI: Frameless open source UI suite.
  • Monica: An open source relationship management system.

Related tools

Having a specification is good, but what if you don’t want to remember so many types? How do you ensure that everyone on the team is actually following the specification? These can all be solved with tools.

Commitizen

It is a common tool that provides a variety of commit Message styles to choose from, such as the Conventional specification we mentioned above. It can be realized by following THE CZ-Conventional – Changelog.

In addition to providing alternative styles, you can modify existing specifications to create your own set of style configurations.

Installation:

npm install commitizen -g
Copy the code

Choose a style:

commitizen init cz-conventional-changelog --save-dev --save-exact
Copy the code

or

commitizen init cz-conventional-changelog --yarn --dev --exact
Copy the code

When committing code, use git CZ instead of Git commit.

commitlint

Linter for commit Messages, used to check messages for non-conforming commit messages.

Commit = commit = commit = commit = commit = commit = commit = commit = commit = commit = commit = commit = commit = commit = commit = commit = commit = commit = commit = commit = commit = commit = commit

Also, commitLint supports configuration to install different styles of configuration, and you can publish and use your own configuration.

Installation:

npm install --save-dev @commitlint/{config-conventional,cli}
Copy the code

Configuration style

echo "module.exports = {extends: ['@commitlint/config-conventional']}" > commitlint.config.js
Copy the code

Use with Git hooks

To install the husky

npm install --save-dev husky
Copy the code

Added configuration in package.json

{
"husky": {"hooks": {"commit-msg": "commitlint -E HUSKY_GIT_PARAMS"}}}Copy the code

Entering a commit Message that does not match the style will fail and will prompt you.

standard-version

Standard-version requires Conventional Commits, which help generate automatically defined versions and CHANGELOG that meet SemVer specifications.

Installation:

npm i --save-dev standard-version
Copy the code

Add configuration to package.json:

{"scripts": {"release": "standard-version" }}
Copy the code

This is the first release. Run this command and generate changeLog

npm run release -- --first-release
Copy the code

After the version change, directly executed

npm run release
Copy the code

Q&A

How to submit multiple types at once

Break up tasks as much as possible and commit each part as it completes to avoid committing too much code at once. In this way, too many files can be modified at one commit, resulting in subsequent maintenance and rollback difficulties.

If there is such a commit, select the type of the most important change and specify the change in the body section.

What should I do if I submit non-standard information

If you use Commitizen or CommitLint, you can almost always commit a Message that complies with the specification. However, you can also select the wrong type, such as fix and commit. Git rebase -i can be used to edit the commit history.

reference

Angular specification: github.com/angular/ang…

But these Commits specification: www.conventionalcommits.org/en/v1.0.0-b…

SemVer specification: semver.org/

Welcome to my public account “front-end xiaoyuan”, I will update the original articles on it regularly.