@@ -96,47 +96,68 @@ smoothly and quickly.
96
96
97
97
### PR Descriptions
98
98
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
100
106
the type of change. Examples: transport, client, server, round_robin, xds,
101
107
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:
102
126
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
+ ```
105
131
106
- * particularly * the sections "First Line" and "Body is Informative" .
132
+ This need not match the PR title .
107
133
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:
111
135
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.
116
137
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.
118
141
119
- ```
120
- RELEASE NOTES:
121
- * <component>: <summary>
122
- ```
142
+ - begin with a capital letter and use complete sentences.
123
143
124
- This need not match the PR title .
144
+ - be as short as possible to describe the change being made .
125
145
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`.
127
148
128
- * be something that gRPC users will understand.
149
+ Here are some examples of good PR descriptions:
129
150
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>
133
153
134
- * begin with a capital letter and use complete sentences.
154
+ Here are some examples of bad PR descriptions
135
155
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>
137
158
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>
140
161
141
162
### PR Process
142
163
0 commit comments