Write a good description of CL
A good description discloses CL recorded it and what changes Why do these changes. It will become part of the history of our version control in permanent, will be read in addition to your reviewer of hundreds of people in the future.
Future developers will find your CL according to the description. Some people may be future because some weak association was not easy to see the details of your changes. If all of the important information in the code, and not in the description, it will be difficult for them to locate your CL.
The first line (PR of title)
- A brief summary of what has been done
- Complete sentences, write the same command like
- Followed by a blank line
__ __ described a first line CL should be a summary of the CL summary of the specific work done, then a blank line. This will see when browsing the history of a piece of code version control most things in the future developers, so the first line should provide enough information so that they do not have to do a general understanding of what your CL, CL or read your away throughout the description.
Traditionally, the first line CL describes a complete sentence, as a write command (imperative sentences). For example, " the Delete The FizzBuzz the RPC and Replace IT with The new new System." Instead of " the Deleting The FizzBuzz the RPC and Replacing IT with The new new System.". However, no other sentence written in the imperative sentence.
Body informative
The remainder of the description should be informative. It may contain a brief description, introduced to solve the problem, why this is the best solution. If this solution is less than what it should be mentioned in the description. If relevant, it should include background information, such as links bug number, benchmark results, and design documents.
Even small details CL should also be noted that, put it in context.
CL bad description
"Fix bug"CL is an inappropriate description. What bug? What did you do to fix it? Other bad similar to that described include:
- “Fix build.”
- “Add patch.”
- “Moving code from A to B.”
- “Phase 1.”
- “Add convenience functions.”
- “kill weird URLs.”
These are part of real CL described. Their authors may believe that they provide useful information, but they do not meet the objectives of a CL described.
Excellent CL Description
Here are some excellent examples described.
Functional changes
rpc: remove size limit on RPC server message freelist.
Servers like FizzBuzz have very large messages and would benefit from reuse. Make the freelist larger, and add a goroutine that frees the freelist entries slowly over time, so that idle servers eventually release all freelist entries.
In front of a few words describe the CL in the end what has been done. The remainder of the description indicate what the problem is resolved, and why this is a good solution, as well as more detailed information on specific implementation.
Reconstruction
Construct a Task with a TimeKeeper to use its TimeStr and Now methods.
Add a Now method to Task, so the borglet() getter method can be removed (which was only used by OOMCandidate to call borglet’s Now method). This replaces the methods on Borglet that delegate to a TimeKeeper.
Allowing Tasks to supply Now is a step toward eliminating the dependency on Borglet. Eventually, collaborators that depend on getting Now from the Task should be changed to use a TimeKeeper directly, but this has been an accommodation to refactoring in small steps.
Continuing the long-range goal of refactoring the Borglet Hierarchy.
The first line describes the CL do, and this change in the past. The remaining portion of the described specific implementations discussed, the context of the CL, the program is not over, and to solve possible future directions. It also explains why do these changes.
Need some context small CL
Create a Python3 build rule for status.py.
This allows consumers who are already using this as in Python3 to depend on a rule that is next to the original status build rule instead of somewhere in their own tree. It encourages new consumers to use Python3 if they can, instead of Python2, and significantly simplifies some automated build file refactoring tools being worked on currently.
The first sentence describes a specific done. The remaining part explains why this change, and a lot of context to the reviewer.
First review before submitting CL Description
CLs may be a huge change during the review. So before submitting CL review description are very valuable, it will ensure that describes the CL still reflects what has been done.