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
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 as
rebaseAnd 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
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.
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
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
fail(), clear(n) and exceptions() are just never called. Delete
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.