Docs: Update PR template to ask for user-visible rationale - #24053
Merged
Conversation
alamb
commented
Aug 2, 2026
| placeholder: > | ||
| A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] | ||
| (This section helps Arrow developers understand the context and *why* for this feature, in addition to the *what*) | ||
| (This section helps DataFusion developers understand the context and *why* for this feature, in addition to the *what*) |
alamb
marked this pull request as ready for review
August 2, 2026 11:12
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #24053 +/- ##
==========================================
- Coverage 80.86% 80.85% -0.01%
==========================================
Files 1101 1101
Lines 375446 375446
Branches 375446 375446
==========================================
- Hits 303592 303585 -7
- Misses 53761 53768 +7
Partials 18093 18093 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
2010YOUY01
reviewed
Aug 3, 2026
|
|
||
| For example, "The code in `foo.rs` doesn't handle nulls" is a symptom of the | ||
| implementation. "COUNT(DISTINCT) returns wrong results when the column contains | ||
| nulls" is the user-visible problem. |
Contributor
There was a problem hiding this comment.
Suggested change
| nulls" is the user-visible problem. | |
| A PR rationale should present a clear chain of reasoning. This helps other contributors understand the intent end to end and engage at any step—for example, by questioning an assumption or proposing an alternative approach. | |
| When a PR description contains only low-level implementation details, reviewers must reconstruct the original intent from the code changes themselves. | |
| Here are the typical steps for describing a bug-fix PR: | |
| 1. What user-visible problem are you trying to solve? | |
| Please explain the problem you are trying to solve in terms of the user-visible behavior, rather than the implementation. | |
| For example, "The code in `foo.rs` doesn't handle nulls" is a symptom of the implementation. "COUNT(DISTINCT) returns wrong results when the column contains nulls" is the user-visible problem. | |
| 2. What is the high-level idea behind the fix? | |
| 3. (In the next 'changes' section) What are the key changes in the PR? | |
| Highlight the changes that are central to the solution. For a large PR, distinguish the core changes from follow-up or propagated fixes. This makes the PR easier to navigate and review. | |
I think we have very similar ideas, but I tried to explain in more detail. It may be a bit verbose, so perhaps we can make it more concise. 🤔 WDYT?
Contributor
Author
There was a problem hiding this comment.
I think this is a bit too verbose for every PR -- how about we add this backstory / content to https://datafusion.apache.org/contributor-guide/index.html#creating-pull-requests and then add a link to that section here?
2010YOUY01
approved these changes
Aug 4, 2026
Contributor
Author
|
Thanks @2010YOUY01 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Which issue does this PR close?
Rationale for this change
PR descriptions are most useful when they describe the problem being solved from the user's point of view, rather than describing what is wrong with some part of the code.
What changes are included in this PR?
.github/pull_request_template.mdto ask authors to explain the problem in terms of user-visible behavior (with an example), and to add theapi changelabel for breaking public API changes.Are these changes tested?
No tests needed: template-only change.
Are there any user-facing changes?
No changes to the code or documentation; contributors will see the updated
templates when opening PRs and feature requests.