From 0ea02fd8c2e436c71042105e880b1b33cdb24ea6 Mon Sep 17 00:00:00 2001 From: Easwar Swaminathan Date: Thu, 18 Sep 2025 19:14:23 +0000 Subject: [PATCH] CONTRIBUTING.md: Clarify the PR description section --- CONTRIBUTING.md | 73 +++++++++++++++++++++++++++++++------------------ 1 file changed, 47 insertions(+), 26 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2079de7b0ed8..c353217f40a3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 #` (to close the issue) or `Updates + #` (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: + * : + ``` - *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 #` to ensure the issue is closed when the PR is merged. Or - use `Updates #` 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: - * : - ``` + - 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. +- +- - * 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. +- +- - 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: + ### PR Process