Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 47 additions & 26 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -96,47 +96,68 @@ smoothly and quickly.

### PR Descriptions

- **PR titles** should start with the name of the component being addressed, or
The title and description of a pull request (PR) becomes a permanent part of our
version control history and may be read by many people over time. It is
therefore important to provide clear and complete information.

- **PR titles** should briefly summarize the change.

1. Should start with the name of the component being addressed, or
the type of change. Examples: transport, client, server, round_robin, xds,
cleanup, deps.

- Read and follow the **guidelines for PR titles and descriptions** here:
https://google.github.io/eng-practices/review/developer/cl-descriptions.html
2. Should be a complete sentence, written as though it was an order. For
example, prefer "Create LRS client at init time" instead of "Creating LRS
client at init time".

- **PR descriptions** should give readers all the context they need to
understand the change. It should include the following:

1. **Tracking Issue**: If the PR addresses an issue, it should be mentioned on
the first line using `Fixes #<issue>` (to close the issue) or `Updates
#<issue>` (if related but not closing). Consider filing an issue if one
doesn’t already exist.

2. **Body** should briefly describe the problem, the solution, and why this
approach was preferred, links to design docs or benchmarks if relevant.

3. **Release Notes** should be the final section of the description. It should
be of the following form:

```
RELEASE NOTES:
* <component>: <summary>
```

*particularly* the sections "First Line" and "Body is Informative".
This need not match the PR title.

Note: your PR description will be used as the git commit message in a
squash-and-merge if your PR is approved. We may make changes to this as
necessary.
The summary must:

- **Does this PR relate to an open issue?** On the first line, please use the
tag `Fixes #<issue>` to ensure the issue is closed when the PR is merged. Or
use `Updates #<issue>` if the PR is related to an open issue, but does not fix
it. Consider filing an issue if one does not already exist.
- be something that gRPC users will understand.

- PR descriptions *must* conclude with **release notes** as follows:
- clearly explain the feature being added, the issue being fixed, or the
behavior being changed, etc. If fixing a bug, be clear about how the bug
can be triggered by an end-user.

```
RELEASE NOTES:
* <component>: <summary>
```
- begin with a capital letter and use complete sentences.

This need not match the PR title.
- be as short as possible to describe the change being made.

The summary must:
If a PR is *not* end-user visible -- e.g. a cleanup, testing change, or
GitHub-related, use `RELEASE NOTES: n/a`.

* be something that gRPC users will understand.
Here are some examples of good PR descriptions:

* clearly explain the feature being added, the issue being fixed, or the
behavior being changed, etc. If fixing a bug, be clear about how the bug
can be triggered by an end-user.
- <https://github.com/grpc/grpc-go/pull/8547>
- <https://github.com/grpc/grpc-go/pull/8528>

* begin with a capital letter and use complete sentences.
Here are some examples of bad PR descriptions

* be as short as possible to describe the change being made.
- <https://github.com/grpc/grpc-go/pull/2992>
- <https://github.com/grpc/grpc-go/pull/2876>

If a PR is *not* end-user visible -- e.g. a cleanup, testing change, or
GitHub-related, use `RELEASE NOTES: n/a`.
See here for complete **guidelines for PR titles and descriptions** here:
<https://google.github.io/eng-practices/review/developer/cl-descriptions.html>

### PR Process

Expand Down