@@ -96,47 +96,68 @@ smoothly and quickly.
9696
9797### PR Descriptions
9898
99- - ** PR titles** should start with the name of the component being addressed, or
99+ The title and description of a pull request (PR) becomes a permanent part of our
100+ version control history and may be read by many people over time. It is
101+ therefore important to provide clear and complete information.
102+
103+ - ** PR titles** should briefly summarize the change.
104+
105+ 1 . Should start with the name of the component being addressed, or
100106 the type of change. Examples: transport, client, server, round_robin, xds,
101107 cleanup, deps.
108+
109+ 2 . Should be a complete sentence, written as though it was an order. For
110+ example, prefer "Create LRS client at init time" instead of "Creating LRS
111+ client at init time".
112+
113+ - ** PR descriptions** should give readers all the context they need to
114+ understand the change. It should include the following:
115+
116+ 1 . ** Tracking Issue** : If the PR addresses an issue, it should be mentioned on
117+ the first line using ` Fixes #<issue> ` (to close the issue) or `Updates
118+ #<issue >` (if related but not closing). Consider filing an issue if one
119+ doesn’t already exist.
120+
121+ 2 . ** Body** should briefly describe the problem, the solution, and why this
122+ approach was preferred, links to design docs or benchmarks if relevant.
123+
124+ 3 . ** Release Notes** should be the final section of the description. It should
125+ be of the following form:
102126
103- - Read and follow the ** guidelines for PR titles and descriptions** here:
104- https://google.github.io/eng-practices/review/developer/cl-descriptions.html
127+ ```
128+ RELEASE NOTES:
129+ * <component>: <summary>
130+ ```
105131
106- * particularly * the sections "First Line" and "Body is Informative" .
132+ This need not match the PR title .
107133
108- Note: your PR description will be used as the git commit message in a
109- squash-and-merge if your PR is approved. We may make changes to this as
110- necessary.
134+ The summary must:
111135
112- - ** Does this PR relate to an open issue?** On the first line, please use the
113- tag ` Fixes #<issue> ` to ensure the issue is closed when the PR is merged. Or
114- use ` Updates #<issue> ` if the PR is related to an open issue, but does not fix
115- it. Consider filing an issue if one does not already exist.
136+ - be something that gRPC users will understand.
116137
117- - PR descriptions * must* conclude with ** release notes** as follows:
138+ - clearly explain the feature being added, the issue being fixed, or the
139+ behavior being changed, etc. If fixing a bug, be clear about how the bug
140+ can be triggered by an end-user.
118141
119- ```
120- RELEASE NOTES:
121- * <component>: <summary>
122- ```
142+ - begin with a capital letter and use complete sentences.
123143
124- This need not match the PR title .
144+ - be as short as possible to describe the change being made .
125145
126- The summary must:
146+ If a PR is *not* end-user visible -- e.g. a cleanup, testing change, or
147+ GitHub-related, use `RELEASE NOTES: n/a`.
127148
128- * be something that gRPC users will understand.
149+ Here are some examples of good PR descriptions:
129150
130- * clearly explain the feature being added, the issue being fixed, or the
131- behavior being changed, etc. If fixing a bug, be clear about how the bug
132- can be triggered by an end-user.
151+ - <https://github.com/grpc/grpc-go/pull/8547>
152+ - <https://github.com/grpc/grpc-go/pull/8528>
133153
134- * begin with a capital letter and use complete sentences.
154+ Here are some examples of bad PR descriptions
135155
136- * be as short as possible to describe the change being made.
156+ - <https://github.com/grpc/grpc-go/pull/2992>
157+ - <https://github.com/grpc/grpc-go/pull/2876>
137158
138- If a PR is * not * end-user visible -- e.g. a cleanup, testing change, or
139- GitHub-related, use ` RELEASE NOTES: n/a ` .
159+ See here for complete **guidelines for PR titles and descriptions** here:
160+ <https://google.github.io/eng-practices/review/developer/cl-descriptions.html>
140161
141162### PR Process
142163
0 commit comments