How to write git submission information

Time:2022-5-14

Why is good submission important?
If you browse the log of GIT warehouse casually, you may find that its submission information is more or less a mess. For example, look at these submissions when I submitted spring earlier:

$ git log --oneline -5 --author cbeams --before "Fri Mar 26 2009"

e5f4b49 Re-adding ConfigurationPostProcessorTests after its brief removal in r814. @Ignore-ing the testCglibClassesAreLoadedJustInTimeForEnhancement() method as it turns out this was one of the culprits in the recent build breakage. The classloader hacking causes subtle downstream effects, breaking unrelated tests. The test method is still useful, but should only be run on a manual basis to ensure CGLIB is not prematurely classloaded, and should not be run as part of the automated build.
2db0f12 fixed two build-breaking issues: + reverted ClassMetadataReadingVisitor to revision 794 + eliminated ConfigurationPostProcessorTests until further investigation determines why it causes downstream tests to fail (such as the seemingly unrelated ClassPathXmlApplicationContextTests)
147709f Tweaks to package-info.java files
22b25e0 Consolidated Util and MutableAnnotationUtils classes into existing AsmUtils
7f96f57 polishing

Compare it with the latest submission in the same warehouse:

$ git log --oneline -5 --author pwebb --before "Sat Aug 30 2014"

5ba3db6 Fix failing CompositePropertySourceTests
84564a0 Rework @PropertySource early parsing logic
e142fd1 Add tests for ImportSelector meta-data
887815f Update docbook dependency and generate epub
ac8326d Polish mockito usage

Which would you prefer to read?
The former is different in length and form; The latter is concise and consistent, and the former occurs by default; The latter will never happen by chance. Although many warehouse logs look like the former, there are exceptions. The Linux kernel is a good example. Look at spring boot, or any warehouse managed by Tim Pope. The contributors of these warehouses know that well-designed git submission information is the best way to convey changes to other developers (even future self). The difference will tell you what has changed, but only submitting information can tell you the reason correctly. Peter Hutter illustrates this very well.

Re establishing the context of a piece of code is wasteful. We can’t completely avoid it, so our efforts should reduce it as much as possible. Submitting information can just do this. Therefore, submitting information can show whether a developer is a good partner.

If you haven’t considered how to write a good git submission, it may be that you don’t spend too much time using git log and related tools. There is a vicious circle: because the submission history is disordered and inconsistent, people don’t spend a lot of time using or taking care of it. And because it is not used or taken care of, it is still unstructured and inconsistent.

This is true for git blank, revert, rebase, log, shortlog, and other subcommands. Reviewing other people’s submissions and pull requests becomes something worth doing, and can suddenly be done independently. Understanding the reasons for what happened a few months or years ago is not only possible, but also effective.

The long-term success of a project depends on its maintainability, and the maintainer has no more powerful tool than his project log. It’s worth taking the time to learn how to maintain it properly. It may be troublesome at first, but it will soon become a habit and eventually become a source of pride and productivity for all participants.

In this article, I only discussed the most basic element of maintaining a healthy submission history: how to write personal submission information. There are other important practices, such as submission suppression, which I won’t talk about here. Maybe I’ll discuss this in a later article.

Most programming languages have established conventions on what is a habitual style, that is, naming, formatting, and so on. Of course, these conventions also change, but most developers agree that choosing a convention and sticking to it is much better than the chaos caused by everyone doing their own things.

The same should be true of how a team handles its submission logs. In order to create a useful revision history, the team should first agree on a convention for submitting information, defining at least the following three points.

Style, marking grammar, wrapping, grammar, case, punctuation. Write these things down, eliminate guesswork, and make them as simple as possible. The final result will be a very consistent log, which is not only a fun to read, but also often read.

Content, what information should be included in the body of the submitted information (if any)? What should not be included?
Metadata. How should the issue tracking ID, pull request number, etc. be referenced?

Fortunately, there are mature conventions on how to become a standard git submission. In fact, many of these are assumed in the way some git commands work. You don’t need to reinvent anything. As long as you follow the following method, you can submit it like an expert.

Seven rules for good git to submit information
Please remember

Summarize the changes in about 50 characters or less

If necessary, provide more detailed explanations. Wrap it up, about 72 characters. In some cases, the first line is considered
The rest is the main body. The blank line between the abstract and the text is very important (unless you omit the text completely).
Unless you completely omit the text); Various tools, such aslogshortlogrebaseAnd so on, there will be problems in the submission process.
And “rebase” and other tools. If you run the two together, there will be confusion.

Explain the problems to be solved in this submission. The point is why
Not how to change (the code will explain).
Does this change have side effects or other unintelligible consequences?
Side effects or other unintelligible consequences? That explains it here.

A blank line is followed by a further paragraph.

-Bullets are also possible

-Typically, items are represented by hyphens or asterisks, preceded by a space.
There is a space in front and a blank line in the middle, but the Convention is
It's different here

If you use a problem tracker, place references to them at the bottom.
like this:

Resolves: #123
See also: #456, #789

Separate the body from the body with a blank line
Although not required, it is best to summarize the modification in a short line (less than 50 characters) at the beginning of the submission, followed by a blank line and a more detailed description. The text before the first blank line in the submission is regarded as the submission title, which will be used throughout GIT. For example, GIT format patch (1) turns a submission into an e-mail, using a title in the subject line and other content submitted in the body.

First, not every submission requires a subject and body. Sometimes it takes only one line, especially when the change is very simple and no further context is required. for instance:

Fix typos in user guide introduction
There is nothing to say; If the reader wants to know what the typo is, she can directly look at the modification itself, that is, use git show or git diff or git log – P.
If you submit something like this on the command line, it’s easy to use the – M option of GIT commit.

Git commit – M “f fix typos in user guide introduction”
However, when a submission needs explanation and explanation, you need to write a text. for instance.

Main control program derezz

This promise threw Tron’s CD into MCP (leading to its disintegration).
And turn it back into a chess game.
It’s not so easy to write a submission with text with the – M option. You’d better use a suitable text editor to write the information. If you haven’t set up an editor for git on the command line, please read this section of Pro GIT.
In any case, it is beneficial to separate the subject from the body when browsing the log. Here are the complete log entries.

$ git log
commit 42e769bdf4894310333942ffc5a15151222a87be
Author: Kevin Flynn <[email protected]>
Date:   Fri Jan 01 00:00:00 1982 -0200
  Main control program derezz

 This promise threw Tron's CD into MCP (leading to its disintegration).
 And turn it back into a chess game.

Now, GIT log – oneline only prints the subject line.

$ git log --oneline
42e769 Derezz the master control program
42e769 derezz's main control program

Or, GIT shortlog, which is submitted by users in groups, also displays only the subject line to achieve a concise effect.

$ git shortlog
Kevin Flynn (1):
      Derezz's main control program

Alan Bradley (1):
       Introduction of safety program "Tron"

Ed Dillinger (3):
      Rename the chess program "MCP"
      Modify chess program
      Upgrade chess program
Walter Gibbs (1):
     Introduce the original chess program
In git, there are many other cases where the distinction between the subject line and the body begins to work, but none of them works without an empty line in the middle.

Limit subject lines to 50 characters
50 characters is not a hard limit, but a rule of thumb. Keeping the subject lines at this length ensures their readability and forces the author to think about explaining what happened in the simplest way.

Tip: if you have difficulty summarizing, you may have submitted too many changes at one time. Strive to achieve atomic submission (this is the subject of a separate post).

GitHub's user interface is fully aware of these conventions. If you exceed the 50 character limit, it will warn you.


Any subject line longer than 72 characters will be truncated with an ellipsis.


Therefore, strive to control within 50 characters, but take into account that 72 are hard limits.

Use uppercase letters in the topic bar
It's as simple as it sounds. All subject lines begin with a capital letter.
for instance.

Accelerate to 88 miles per hour
Instead of:
instead of:

accelerate to 88 miles per hour
Don't end the subject line with a period
In the subject line, trailing punctuation is unnecessary. In addition, space is valuable when you try to keep them at 50 characters or less.
example.

Open the pod bay doors
Instead of:
instead of:

Open the pod bay doors.
Use imperative mood in subject line
祈使语气只是意味着 “像发出命令或指令一样说或写”。举几个example.

Clean your room 
Close the door
*Take out the garbage
Each of the seven rules you read now is written in imperative ("wrap your body at 72 characters", etc.).
Imperative sounds a little rude; That's why we don't use it often. But it works well for git submitted subject lines. One reason is that when git creates a submission on your behalf, it will use the command itself.
For example, the default information created when using git merge is like this

Merge branch 'myfeature'
When using git revert.

Revert "Add the thing with the stuff"

This reverts commit cc87791524aedd593cff5a74532befe7ab69ce9d.
Or click the "merge" button of GitHub pull request.

Merge pull request #123 from someuser/somebranch

Therefore, when you write your submission in imperative, you are following git’s own built-in conventions. for instance

Readability of reconstruction subsystem x
Update getting started documentation
Delete obsolete methods
Release version 1.0.0
This may be a little awkward at first. We are more used to speaking in an indicative tone, which is about reporting the facts. This is why the information submitted is often read like this in the end.

Fixed bug with Y
Changing behavior of X
Sometimes the submitted information is written as a description of its content.

More fixes for broken stuff
Sweet new API methods
To dispel any doubts, here is a simple rule that allows you to do well every time.
A correct git submission topic line should always be able to complete the following sentences.

If applied, this commit will your subject line here

for instance:

If applied, this submission will refactor subsystem x to improve readability.
If applied, this submission will update the getting started document
If applied, this submission will delete the obsolete method
If applied, this submission will release version 1.0.0.
If applied, this submission will merge the #123 pull requests from the user / branch.
Note that this does not work for other non implicit forms.

If applied, this submission will fix Y’s errors.
If applied, this submission will change X’s behavior.
If applied, this submission will fix more broken things
If applied, this submission will provide new API methods.
Please remember. The use of imperative sentences is important only in the subject line. You can relax this restriction when writing the text.

Wrap text in 72 characters
Git never automatically wraps text. When you write the body of your submission, you must pay attention to its right margin and wrap the text manually.
It is recommended to do this at 72 characters, so git has enough space to indent the text and keep all content within 80 characters.
A good text editor can help you. For example, configuring VIM is easy. When you write a git submission, it can wrap text in 72 characters. Traditionally, however, ides have been bad at providing intelligent support for submitting information (although IntelliJ idea has finally become better in recent releases).

Use the text to explain what and why and how.
This submission from bitcoin core is a good example to explain what changes and why.

c`
ommit eb0b56b19017ab5c16c745e6da39c53126924ed6
Author: Pieter Wuille mailto:[email protected]
Date: Fri Aug 1 22:57:55 2014 +0200

Simplify serialize.h’s exception handling

Remove the ‘state’ and ‘exceptmask’ from serialize.h’s stream
implementations, as well as related methods.

As exceptmask always included ‘failbit’, and setstate was always
called with bits = failbit, all it did was immediately raise an
exception. Get rid of those variables, and replace the setstate
with direct exception throwing (which also removes some dead
code).

As a result, good() is never reached after a failure (there are
only 2 calls, one of which is in tests), and can just be replaced
by !eof().

fail(), clear(n) and exceptions() are just never called. Delete
them.

Look at the complete differences and think about how much time the author spends providing this background here, saving his peers and future submitters. If he doesn't, he may disappear forever.
In most cases, you don't have to write details about how to make changes. The code is usually self-evident in this regard (if the code is very complex and needs to be explained in prose, it is the role of source code annotation). You just need to focus on clearly explaining why you made the change first - the way you worked before the change (and the problems therein), the way you work now, and why you decided to solve it in this way.
The defender who will thank you in the future may be yourself.

Tips 
Learn to love the command line. Leave ide behind

Like git's subcommands, it's wise to embrace the command line. Git is very powerful; The same is true for ides, but in different ways. I use the IDE (IntelliJ idea) every day, and I have also widely used other ides (eclipse), but I have never seen the integration of GIT by ide compared with the convenience and power of the command line (once you understand it).

Some ide functions related to git are very valuable, such as calling git RM when you delete a file and doing the right thing with git when you rename a file. Everything crashes when you start trying to commit, merge, relocate, or do complex historical analysis through the IDE.
To give full play to git's power, you have to use the command line.