例如,说\"**Delete** the FizzBuzz RPC and **replace** it with the new system.",而不是\"**Deleting** the FizzBuzz RPC and **replacing** it with the new system."。
不过,你不必把其余的描述写成祈使句。
## First Line {#firstline}
## 正文内容丰富 {#informative}
* Short summary of what is being done.
* Complete sentence, written as though it was an order.
* Follow by empty line.
其余描述应该是具有丰富的内容。它可能包括对正在解决的问题的简要描述,以及为什么这是最好的方法。
如果这种方法有任何缺点,就应该提到。
将相关的背景信息(例如bug数目,基准测试结果),以及设计文档的链接。
即使是很小的CL也值得关注细节。请将来龙去脉放入CL中。
The **first line** of a CL description should be a short summary of
*specifically***what***is being done by the CL*, followed by a blank line.
This is what most future code searchers will see when they are browsing the
version control history of a piece of code, so this first line should be
informative enough that they don't have to read your CL or its whole description
just to get a general idea of what your CL actually *did*.
## 不好的CL描述 {#bad}
By tradition, the first line of a CL description is a complete sentence, written
as though it were an order (an imperative sentence). For example, say
\"**Delete** the FizzBuzz RPC and **replace** it with the new system." instead
of \"**Deleting** the FizzBuzz RPC and **replacing** it with the new system."
You don't have to write the rest of the description as an imperative sentence,
though.
## Body is Informative {#informative}
The rest of the description should be informative. It might include a brief
description of the problem that's being solved, and why this is the best
approach. If there are any shortcomings to the approach, they should be
mentioned. If relevant, include background information such as bug numbers,
benchmark results, and links to design documents.
Even small CLs deserve a little attention to detail. Put the CL in context.
## Bad CL Descriptions {#bad}
"Fix bug" is an inadequate CL description. What bug? What did you do to fix it?
Other similarly bad descriptions include:
"Fix bug"是一个不充分的CL描述。是什么bug?你是怎么修复它的?
其他一些相似的不好的CL描述:
- "Fix build."
- "Add patch."
...
...
@@ -55,15 +37,13 @@ Other similarly bad descriptions include:
- "Add convenience functions."
- "kill weird URLs."
Some of those are real CL descriptions. Their authors may believe they are
providing useful information, but they are not serving the purpose of a CL