Skip to content

Commit 279547b

Browse files
committed
CONTRIBUTING.md: Clarify the PR description section
1 parent e8ad657 commit 279547b

File tree

1 file changed

+47
-26
lines changed

1 file changed

+47
-26
lines changed

CONTRIBUTING.md

Lines changed: 47 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -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

Comments
 (0)