git commit message writing guide

0. Commit message preparation guide

[statement] refer to the angular code specification and some blogs, only learning records, non-commercial.

1. General

When Git is used to submit code in daily development, it is required to write git commit message, otherwise there will be no submission code.

As a change description, the commit message is saved in the commit history for easy backtracking.

The standardized log can not only help others review, but also effectively output CHANGELOG, and even greatly improve the R & D quality of the project.

What are the benefits of standardizing git commit?

  • It is convenient for programmers to trace the submission history and understand what happened.
  • Once the commit message is constrained, it means that we will carefully submit each time, and we can't put all kinds of changes in a git commit. In this way, the history of the whole code change will be clearer.
  • Only the formatted commit message can be used to automatically output the Change log.

This chapter mainly studies the Angular specification.

2. Angular

2.1. Angular specification

The Commit message consists of three parts: Header, Body and Footer.

The Header is required, and the Body and Footer can be omitted.

No matter which part it is, no line can exceed 100 characters. This is to avoid the effect of automatic line feed on aesthetics and make it easier to read on github and other git tools.

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

Title Line: within 50 characters, describing the main changes

Main content: more detailed description text, within 72 characters recommended. The information to be described includes: 
    - Why is this change necessary? It may be used to repair a bug，Add one feature，Improve performance, reliability, stability, etc
    - How did he solve the problem? Specifically describe the steps to solve the problem
    - Whether there are side effects and risks? 

Tail: if necessary, you can add a link to issue Address or other documents, or close a issue.

2.2. Parameter description

2.2.1. Header

When viewing git log, common git client tools often only display the contents of the first line of git commit message. The function of header is to standardize the contents of the first line, so that we can see the contents of each commit at a glance when browsing git log.

The Header section in the specification has only one line, including three fields: type (required), scope (optional) and subject (required).

2.2.1.1. type

Type: represents the type of a submission, such as fixing a bug or adding a new feature.

Type typeAnnotation
featNew features
fixbug fix
docsDocument related changes
styleThe formatting changes to the code did not change the code logic
refactorRefactoring code or other optimization measures will not affect existing functions in theory
perfImprove performance
testAdd or modify test cases
buildThe code logic has not changed due to the changes in the engineering of the project. (including but not limited to documents, code generation, etc.)
ciChanges to CI profiles and scripts
depsUpgrade dependency
choreChange the construction process, or add dependent libraries, tools, etc
revertRoll back an earlier commit
releaseRelease version submission
*
  • When a change includes main type and special type, the main type shall be adopted uniformly.
  • If the type is feat and fix, the commit will definitely appear in the Change log. Other situations (docs, chore, style, refactor, test) are up to you to decide whether to put them in the Change log. It is recommended not to.
  • Add "!" after type Represents a significant code change.

2.2.1.2. scope

Scope: used to mark the scope of the modified file. This range can correspond to a function or folder.

2.2.1.3. subject

The overview of commit should be concise and comprehensive. No more than 50 characters. It is recommended to comply with 50/72 formatting

  • Start with a verb and use the first person present tense: for example, you should use change instead of changed or changes
  • Don't capitalize the first letter
  • There is no period at the end of the sentence (.)

Example

fix(DAO):User query missing username attribute 
feat(Controller):User query interface development

2.2.2. Body part (can be saved)

The Body part is a detailed description of this commit, which can be divided into multiple lines. It is recommended to comply with 50/72 formatting. Here is an example.

More detailed explanatory text, if necessary.  Wrap it to 
about 72 characters or so. 

Further paragraphs come after blank lines.

- Bullet points are okay, too
- Use a hanging indent
  1. Use the first person present tense, such as fix, add, change instead of fixed, added, changed or changes.
  2. Never forget that line 2 is empty.
  3. Use Line break to split the submitted information, making it easier to read in some software.
  4. Please limit each submission to one logical function. And, if possible, decompose it appropriately into multiple small updates so that each small submission is easier to understand.
  5. The motivation for code changes should be explained and compared with previous behavior.

2.2.3. Footer (can be saved)

footer can contain some major changes or deprecations, such as incompatible modifications, which need to be clearly described here. You can also reference the relevant issue or other PR.

BREAKING CHANGE: <breaking change summary>
<BLANK LINE>
<breaking change description + migration instructions>
<BLANK LINE>
<BLANK LINE>
Fixes #<issue number>

or

DEPRECATED: <what is deprecated>
<BLANK LINE>
<deprecation description + recommended update path>
<BLANK LINE>
<BLANK LINE>
Closes #<pr number>

Major changes should begin with the phrase "BREAKING CHANGE:" followed by a summary of major changes, blank lines, and a detailed description of major changes, including migration instructions.

Similarly, the DEPRECATED part should begin with "DEPRECATED:" followed by a short description of the DEPRECATED content, an empty line, and a detailed description of the DEPRECATED content, which also refers to the recommended update path.

The Footer section is only used in two cases: incompatible change and closing Issue.

  1. Incompatible changes

    If the current code is incompatible with the previous version, such as deleting some functions and changing parameters. The Footer section starts with BREAKING CHANGE, followed by a description of the change, the reason for the change and the migration method.

    BREAKING CHANGE: isolate scope bindings definition has changed.

    To migrate the code follow the example below:

    Before:

    scope: {
      myAttr: 'attribute',
    }

    After:

    scope: {
      myAttr: '@',
    }

    The removed `inject` wasn't generaly useful for directives so there should be no code using it.

  2. Close Issue

    If the current commit is for an issue, you can close the issue in the Footer section.

    Closes #234

    You can also close multiple issue s at once.

    Closes #123, #245, #992

2.3.Revert

In another special case, if the current commit is used to revoke the previous commit, it must start with revert: followed by the Header of the revoked commit.

# Head: revert: < < head of the commit to be revoked >
# body: This reverts commit <commit-hash>.
# eg:
	revert: docs add README.md
	This reverts commit a2d04c0b914785e4ff0cdf4baeea84d8611c7a61.

Example:

revert: feat(pencil): add 'graphiteWidth' option

This reverts commit 667ecc1654a317a13331b17617d973392f415f02.

The format of the Body part is fixed and must be written as this reverts commit < hash >, Where hash is the SHA identifier of the revoked commit.

If the current commit and the revoked commit are in the same release, they will not appear in the Change log. If they are in different releases, the current commit will appear under the Reverts subheading of the Change log.

3. Commit example reference

feat($browser): onUrlChange event (popstate/hashchange/polling)

Added new event to $browser:
- forward popstate event if available
- forward hashchange event if popstate not available
- do polling when neither popstate nor hashchange available

Breaks $browser.onHashChange, which was removed (use onUrlChange instead)

fix($compile): couple of unit tests for IE9

Older IEs serialize html uppercased, but IE9 does not
Would be better to expect case insensitive, unfortunately jasmine does
not allow to user regexps for throw expectations.

Closes #351

docs(guide): updated fixed docs from Google Docs

Couple of typos fixed:
- indentation
- batchLogbatchLog -> batchLog
- start periodic checking
- missing brace

4. Git configuration Commit template

Modify ~ / gitconfig, add:

[commit]

template = ~/.gitmessage

New ~ / The contents of gitmessage can be as follows:

# headr: <type>(<scope>): <subject>
# - type: feat, fix, docs, style, refactor, test, chore
# - scope: can be empty
# - subject: start with verb (such as 'change'), 50-character line
#
# body: 72-character wrapped. This should answer:
# * Why was this change necessary?
# * How does it address the problem?
# * Are there any side effects?
#
# footer:
# - Include a link to the issue.
# - BREAKING CHANGE
#

5.github submission mode

The format of Commit message depends on Github Issue

This way of working expects the team to use Github's Project and Issue to manage development tasks. In this case, the Header part of the Commit message should contain Issue Number.

[#123] Diverting power from warp drive to torpedoes
[Closes #123] Torpedoes now sufficiently powered
[Closes #123][#124][#125] Torpedoes now sufficiently powered

Message Template

[<optional state> #issueid] (50 chars or less) summary of changes

More detailed explanatory text, if necessary. Wrap it to about 72
characters or so.

Further paragraphs come after blank lines.

- Bullet points are okay, too

- Typically a hyphen or asterisk is used for the bullet, preceded by a
single space, with blank lines in between, but conventions vary here

Note to answer the following information

  1. Why is this revision necessary?

    Tell Reviewers what changes your submission contains. Make it easier for them to review code and ignore irrelevant changes.

  2. How to solve the problem?

    This is not about technical details. Look at the following two examples:

    • Introduce a red/black tree to increase search speed
    • Remove , which was causing

    If your changes are particularly obvious, you can ignore this.

  3. Where are these changes likely to affect?

    This is the question you need to answer most. Because it will help you find that too many changes have been made in a branch or commit. Try to make only 1 or 2 changes for a submission.

    Your team should have its own behavior rules that specify the maximum number of functional modifications that can be included in each commit and branch.

example:

Fix bug where user can't signup.

[Bug #2873942]

Users were unable to register if they hadn't visited the plans
and pricing page because we expected that tracking
information to exist for the logs we create after a user
signs up.  I fixed this by adding a check to the logger
to ensure that if that information was not available
we weren't trying to write it.

Redirect user to the requested page after login

https://trello.com/path/to/relevant/card

Users were being redirected to the home page after login, which is less
useful than redirecting to the page they had originally requested before
being redirected to the login form.

* Store requested path in a session variable
* Redirect to the stored location after successfully logging in the user

Keywords: git

Added by bnownlater on Wed, 22 Dec 2021 02:17:41 +0200

Popular Keywords

©2024 Programming VIP