1. Git commit specification

As an essential tool for developers, code submission is a very frequent operation, and for team specification construction, Git submission information specification is a very necessary work.

1.1 Why should the Submission of information be regulated

First of all, it is definitely necessary to standardize the submission of information. Here are some benefits:

  • Let project maintainers or users know what changes have been committed
  • A clear history, you might need to look it up one day
  • Normative commit records can be used to automatically generate a CHANGELOG (changelog.md)
  • Triggers the build and deployment process based on the commit type

1.2 What specifications are used?

One of the most popular schemes on the market today is Conventional Commits, which are inspired by Angular commit guidelines and are largely based on them. The compact commit specification is a lightweight convention based on commit messages. It provides a simple set of rules for creating a clear commit history; This makes it easier to write automation tools based on specifications. This convention is consistent with SemVer, describing new features, bug fixes, and destructive changes in the commit message. Its message format is as follows:

Comments for submissions should include at least four prefixes to help each other understand what has changed

< type >[optional scope]: < description >[optional text] [optional footnote]Copy the code

1.3 The Commit Message specification is landed

Currently, the community has several specifications for how to write Commit messages. referencePresents the specificationIt is the most widely used writing method, more reasonable and systematic, and there are supporting tools. The front frameAngular.jsThis specification is adopted. The diagram below:Here is a structure for the canonical information

< type > (< scope >) : < subject > / / short line < body > / / short line < footer >Copy the code

A Git Commit message consists of three parts: a header, an optional body, an optional footer, Break changes(deleted) ** Header is mandatory. `

1, the type,

Type specifies the commit type. Two major types – feat and fix – and five special types – Docs, Style, build, refactor, and Revert are agreed. The other types are not used for now.

The main type

  • Feat: Add features
  • Fix: Fix a bug

A special type

  • Docs: Documentation changes
  • Style: format changes (changes that do not affect code running)
  • Revert: A message printed by git Revert
  • Build: changes to a construction tool or external dependency, such as Webpack, NPM
  • Refactor: refactoring code (i.e., code changes that are not new functionality or bug fixes)

Do not use type for now

  • Merge: Merge and commit when resolving conflicts without making code changes
  • Chore: a chore in the auxiliary, or any other chore, etc
  • Test: Add tests or modify existing tests
  • Perf: changes to improve performance
  • Ci: Changes related to CI (Continuous Integration Services)

When a change includes both the primary and special types, the primary type is used uniformly.

If type is feat and fix, then the COMMIT will definitely appear in the Change log. In other cases (Docs, chore, Style, Refactor, Test) it is up to you to include the Change log or not.

2, the scope,

Scope is mandatory and contains a maximum of 50 characters in English and Chinese. If English is used, it must be capitized and used to describe the scope of the change. The format is project name or module name, for example, Opinions /topic. If a commit changes multiple modules, you are advised to split them into multiple commits for better tracking and maintenance.

3, the body

Fill in the detailed description of body, which mainly describes the situation before the change and the motivation for the change. For minor changes, it is not required, but for major needs and updates, body must be added to explain.

4, footer

Optional. For Example, if you use gitlab, you need to comment on the issue link to Example Commit Message

5 、break changes

Break changes Indicates whether a destructive change is generated. This parameter must be specified when the change involves break changes, such as version upgrade, interface parameter reduction, interface deletion, and migration.

The sample

Feat (Order process): development payment page Feat (order process): joint adjustment payment functionCopy the code

Every commit should be atomic, either to fix bugs, new features, document changes, etc. Never allow multiple types to be mixed together, otherwise code review will be difficult.

See the Contract Submission Specification for more details

1.4 Quick Start

How to constrain specifications, install CommitLint and CommItizen specifications, and write commit messages that conform to the specifications

1. Install Commitizen & CZ-Conventional – Changelog globally

Commitizen is a tool for writing qualified Commit messages instead of Git commit directives. The CZ-Conventional Changelog adapter provides the Conventional Changelog standard (the conventional submission standard). Depending on your needs, you can use different adapters.

npm install -g commitizen cz-conventional-changelog
echo '{ "path": "cz-conventional-changelog" }' > ~/.czrc
Copy the code

After the installation, you can use Git cz directly instead of Git Commit.

In global mode, the ~/. CZRC configuration file is required to specify Adapter for CommItizen.

Commitlint & Husky installed in the project

Commitlint is responsible for formatting the Commit message, and Husky is responsible for providing git hooks that are easier to use.

# Use npm
npm i -D husky @commitlint/config-conventional @commitlint/cli

# Use yarn
yarn add husky @commitlint/config-conventional @commitlint/cli -D
Copy the code

Commitlint can only do format specifications, not content. The quality of our content is up to us.

3. Add configurations

Create commitlint. Config. Js

# In the same path as package.json

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

The introduction of husky

# package.json { ... ."husky": {
"hooks": {
"commit-msg": "commitlint -e $GIT_PARAMS"}}Copy the code

4, the use of

Run git cz to enter interactive mode, and enter the values as prompted

1.Select the type of change that youWhat is the scope of this change (e.g. component or file name)? 3.Write a short, imperative tense description of the change: 4.Provide a longer description of the change: (Press Enter to skip) Write a long description of the changes () Is (y/n) a destructive modification? Default n (
      

       ) 6.Does this change affect any Openreve issues? What problem does the (y/n) change fix? The default n (< footer >)
      
Copy the code

The format of the generated COMMIT message is as follows:

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

When completed, Husky calls commitLint to verify the format of the message. By default, type and Subject are mandatory.

Any git commit option can be used with git cz, such as git cz -a

2. Git branch management

Git branch management and naming conventions

2.1 Branch classification

Git master (reserved branch) : master, release

Git dev dev/[function-username] Git dev dev/[function-username]

Git: feature/[function], hotfix/, release/

2.2 Branch Introduction

2.2.1 main branch

  • Master: The code that corresponds to the online (official environment). Once the version is online, the tester sends the merge Matser email, and the developer merges the tag version to the Master branch.
  • Release: Merge the release branch with the master branch after the pre-release environment has passed and before going online.

2.2.2 dev, dev/[function-username] Development branch

  • Dev: The dev branch is used for daily functional iterative development, initially pulled from master, and all subsequent functional development is merged back into this branch for collaborative development.
  • Merge feature/[function] merge feature/[function] merge feature/[function] merge feature/[function]

2.2.3 Feature /[function

Pull from master for new requirement (version) development

  • Feature /[function] : merge the dev branch and delete the branch.
  • Hotfix /* : to fix a branch, if you find a bug in an online release, you need to pull it from the master branch to fix the bug. * indicates the version number + phase number
  • release/: Pre-release branch (optional), pulled from master, to ensure that the current version is iterated on the latest online version and can handle conflicts with online code. The task assist branch must pull a release/ after the test environment has passed and before moving on to the pre-release environmentBranch.The id is the corresponding dev/Or hotfix / * *

2.3 Branch Naming

2.3.1 Requirement (version) development

Pull dev branch from master

Branch naming convention: type – version number

Dev - v2.0.1 release - v2.0.1Copy the code

Tag Naming convention: type – version number – period number

Dev - v2.0.1-102401 release - v2.0.1-102401Copy the code

2.3.2 Online Problem handling

Pull the HotFix branch from master

Branch naming rule: type – Hotfix

Tag Naming convention: type – hotfix – period number

Branches:

 hotfix-dateError

 release-dateError
Copy the code

Tag:

 hotfix-dateError-102401

 release-dateError-102401
Copy the code

3. Code management

To manage the warehouse, this is the most common merge method: first, merge in thegitLabCreate a repository for each developer in the current project and have them develop on the corresponding branch. thencloneThis warehouse. When the team needs togitLabWhen uploading code, you need to synchronize your own code to the corresponding branch of your remote repository, and then switch to the local main branch to merge the branch code developed locally. If there is a conflict, you need to resolve the conflict locally, and then synchronize the code to the remote main branch.