Internal change

PiperOrigin-RevId: 298411617

review/developer/cl-descriptions.md

@@ -21,13 +21,15 @@ locate your 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*.
+This is what appears in version control history summaries, so it should be
+informative enough that future code searchers don't have to read your CL or its
+whole description to understand what your CL actually *did* or how it differs
+from other CLs. That is, the first line should stand alone, allowing readers to
+skim through code history much faster.
 
 Try to keep your first line short, focused, and to the point.
 The clarity and utility to the reader should be the top concern.
+
 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
@@ -62,9 +64,8 @@ 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
-description.
+Some of those are real CL descriptions. Although short, they do not provide
+enough useful information.
 
 ## Good CL Descriptions {#good}
 
@@ -120,6 +121,14 @@ The first sentence describes what's actually being done. The rest of the
 description explains *why* the change is being made and gives the reviewer a lot
 of context.
 
+## Generated CL descriptions
+
+Some CLs are generated by tools. Whenever possible, their descriptions
+should also follow the advice here.  That is, their first line should be short,
+focused, and stand alone, and the CL description body should include informative
+details that help reviewers and future code searchers understand each CL's
+effect.
+
 ## Review the description before submitting the CL
 
 CLs can undergo significant change during review. It can be worthwhile to review