Git submission specification

Time:2021-9-27

Git commit specifications and considerations

Please read:

  • How to Write a Git Commit Message
  • Commit messages – Good practices
  • Naming conventions for angular.js

What is a good commit?

  1. A commit should contain only one change logic, and multiple change logic should split multiple commits
  2. Easy code review (multiple small commits are easier to review than one large commit)
  3. The workload of a change within 200 lines of code or within 4 hours (if it exceeds, consider splitting the commit)
  4. The submission history is easy to read and understand how a branch is completed
  5. Easy to revert in the future
  6. I’m not sure what a reasonable commit is? = > Ask code reviewer for advice
  7. If multiple commits complete the same task, you should consider merging (squash / amend)
  8. Prefer to split into multiple commitments before merging (simple operation); Don’t submit a large commit and split it later (it’s difficult to operate)
  9. Reviewer has the right to return and ask for re splitting or merging commitments. Because a big commit will be very difficult to review.

Commit message specification

A good commit message should be understood at a glance:

  • Purpose of operation (subject)
  • Changed scope or module (SCOPE)
  • Type of operation

These messages should be placed in the first line (header) of the commit message. Commit message allows you to enter multiple lines of messages, so the details should be placed in the following body and footer.

This commit message specification mainly refers to the naming specification of angular.js. When submitting a commit, the message must conform to the following three parts:

  1. Header (or title; necessary): one line can understand the summary of the commit
  2. Body (not necessary): specify the content and the message to the reviewer.
  3. Footer (or note: not necessary): indicates which ticket has been solved.

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

Notes on commit message format

  • The scope bracket of the header uses English semi type and is closely connected with type (it looks like a function); The colon is in English half type and must be followed by a blank.
  • The header should be controlled within 50 words as far as possible. If it is too long, it should be considered to simplify the description
  • Each line should be no more than 72 words apart. If it is too long, it should be typed and wrapped by itself
  • There should be a blank line between header / body / footer.
  • The header has strict format specification, and the purpose of a commit must be described in one line (see the description below).
  • The body should describe “what” and “why”, rather than “how”
  • The footer explains which tickets have been completed
  • The commit itself should provide sufficient information to the reviewer, and should not make additional instructions in the merge request.

example

Multiple commit history for branches:

//The branch is’ feat / jira-388-new-api-to-update-user-info ‘/ / contains the following submissions (only header) * test (unit test): add a webapi test

*Update (pods): update the third-party suite afnetworking

*Feat (API): the API of update user is added and implemented

*Feat (user UI): add a page for editing user information

*Feat (CACHE): add the apicache class and implement the cache function

*Feat (default picture): when there is no custom picture, the internal avatar picture

*Chore (compilation setting): info.plist compilation setting

*Docs (readme): modify the readme file description to complete the API module

Or refer to the submission history of the conventional changelog

< type > format description

Like branch names, the following classifications are used (defined by the naming convention of angular.js):

  • Feat: changed functions, new development requirements, third-party library introduction
  • Fix: fix the bug (no matter on which main branch)
  • Add: Add File fi
  • Refactor: refactor and adjust the architecture without adding new functions and fixing bugs (but test code may be added)
  • Perf: improve efficiency and optimize
  • Test: mainly adding tests (possibly accompanied by refactoring)

And add the following allowed types:

  • Update (extracted from the original feat): change the existing requirements and update the third-party library
  • Deprecated (extracted from the original feed): obsolete functions and third-party libraries. Usually, instead of deleting it directly, you use conditional compilation, or move the code and resources to an obsolete folder for future recovery.

< scope > format description

This section indicates the scope of the change. However, a good scope should point out the scope of the impact of this change, let the code reviewers know and let the testers know what to test. If the cache is moved, write the cache, change the payment module, write the payment, etc., so that the impact scope or module can be seen quickly.

Here are some suggestions:

  • In a simple word to describe, the more concise the better
  • It can be defined by abbreviations or abbreviations, as long as everyone knows
  • Similarly, everyone should use the same scope to describe a scope, and the case should be the same (do not use multiple words to explain the same scope).
  • The description of scope should not contain blank space. If it is an English word, use camel case
  • Allow other developers to guess the scope you may modify (a file, a folder… Etc.)
  • It can make the tester more conceptual and know the parts affected by your modification of the code
  • It may be better to break things in different ranges into different commitments.
  • If you really can’t think of a proper noun, you can use a general term, such as fix (ERR) and fix (Bug)
  • If the changes are too complicated, you can write (MISC) (Miscellaneous). (not recommended)
  • If there is really nothing to describe the scope of change, don’t write scope. (not recommended)

For example:

  • If the type is test, the scope may be unittest, uitest, behaviortest
  • If the type is perf, the scope may be loadingtime, memoryfoot

< subject > format description

  • Start with a verb and command mood (add, delete, update, modify), instead of the past tense or gerund (added, adding)
  • The size of the beginning is not necessary; In addition to proper nouns, try to be all lowercase
  • There is no need to add a full stop at the end of the sentence

matters needing attention

A commit has only one code set

A commit should contain all the code and resources needed for the release.

Many developers now use third-party suites and manage them with automated tools. These automation tools can set the minimum version that the third-party library depends on, and provide an automatic update mechanism.

If the time code of each checkout from the same submission is different (for example, the dependent remote library has been updated), the execution result may be different from that packaged before, which will increase the difficulty and additional cost of clarifying the problem.

Therefore, when submitting a commit, the version of the currently used third-party library should be fixed to ensure that the compilation results checked out at any time will always be consistent and get the same results.

You should not use code comments to control packaging

Many projects use conditional compilation to control compilation conditions (such as C macros). For example, when developing, testing and launching the version, set different URLs and API keys to access the server.

However, it is not allowed to use “comment / uncomment” to determine which code and variable settings should be used during packaging. Because this will bring some problems:

  1. Each time you publish, check whether all variables have correct comments / uncomments. This takes a long time and is easy to make mistakes.
  2. In case of errors, the cost of finding problems is high, because it is not sure whether the comments at the time of compilation are correct.
  3. Automated packaging cannot be achieved (the automation tool does not change the code)

Therefore, you should use scheme instead of comment / uncomment to control the conditional parameters of compilation / packaging.

In addition, if some code needs to be removed temporarily, it should also be removed by conditional compilation rather than annotation.

Do not arbitrarily change the branch history of joint development

  • The common branches (especially the main branches) should not change the history arbitrarily, which will lead to development differences after synchronization.
  • Before pushing the changes to the remote end, please make sure that there is no problem, because after pushing, it will become a jointly developed remote branch, and arbitrary changes will easily cause trouble at that time. We will force general developers not to push the main branch, but to merge into the main branch through merge request.
  • If you want to cancel a past commit, use revert
  • If you have to modify the common branch, you should remind everyone before operation and merge the code first.
  • When pulling remote code, always use pull — rebase instead of simply using pull (merge) to avoid accidental merging due to differences with the remote.

Always rebase and always non fast forward merge are used when merging branches

As for whether to use always rebase or always merge, there have always been supporters of both factions, with their own advantages and disadvantages. For more discussion, please refer to this “git team workflows: merge or rebase?” or “getting solid at git rebase vs. merge”.

Using rebase can bring clear submission history and avoid historical confusion caused by multi person development. However, for some notes on using rebase, please refer to the “the golden rule of rebasing”.

As for always non fast forward merge, it can make up for the disadvantage that rebase and fast forward merge form a single line: it is unable to track the beginning and end of a development. This is also the standard of GIT flow.

Do not use git add. You should review the code before submitting it

  • It is not recommended to use the command line to use add / commit. It is recommended to use a graphical tool to execute (such as sourcetree)
  • Don’t use git add. Unless you have reviewed all the required submissions by yourself
  • Try not to use git commit – M “…” operation. Commit message should conform to the specification (there may be multiple lines)
  • Before all add / commit, you must self review, including:
  • Review files: whether the files (including pictures and other resources) that should not be submitted or forgot to be submitted are correctly contained.
  • Review code: whether there is any code that should not be submitted or forgotten to modify.
  • The vast majority of errors can be found during self review.

The operation of changing git submission history must be confirmed after each step of operation

  • Each operation will change the instruction of submitting history. You should check whether the operation is successful immediately after the operation
  • Especially beginners who operate add, commit, rebase, merge and pull must check after operation. If there is a problem, eliminate it immediately.
  • It is recommended to check with graphical tools or git log — oneline — graph — correct — all.