PYTHON-3922: Contributor PR Template (#1358)
* Added Basic PR Template * Update .github/workflows/pull_request_template.md * changed the CONTRIBUTING.rst * added some bold spaces and sleek linking * slight rearrangement of Template Breakdown section * changed template breakdown to sub-bullets * addressed PR resolutions * Update CONTRIBUTING.rst Co-authored-by: Steven Silvester <steven.silvester@ieee.org> * Apply suggestions from code review Co-authored-by: Steven Silvester <steven.silvester@ieee.org> * added blurb to include accompanying JIRA ticket * added some more punctuation --------- Co-authored-by: Steven Silvester <steven.silvester@ieee.org>
This commit is contained in:
parent
6787187f70
commit
ee9cf10976
23
.github/workflows/pull_request_template.md
vendored
Normal file
23
.github/workflows/pull_request_template.md
vendored
Normal file
@ -0,0 +1,23 @@
|
||||
# [JIRA Ticket ID](Link to Ticket)
|
||||
<!-- Please provide explicit URL link to the corresponding JIRA ticket. -->
|
||||
|
||||
# Summary
|
||||
<!-- Please provide a high level overview of what changes have been made. -->
|
||||
|
||||
# Changes in this PR
|
||||
<!-- Highlight any high level architecture changes if the summary doesn't already cover the scope. -->
|
||||
|
||||
# Test Plan
|
||||
<!-- Talk through any unit tests added, and if this is a bug fix, please add repro steps in the event the fix needs to be verified. -->
|
||||
|
||||
# Screenshots (Optional)
|
||||
<!-- Add a before and after picture to indicate changes. -->
|
||||
|
||||
# Callouts or Follow-up items (Optional)
|
||||
<!-- Any additional info not already specified in the PR including but not limited to:
|
||||
|
||||
1. Potential stakeholders
|
||||
2. Slack threads etc.
|
||||
3. Implementation details that need additional oversight
|
||||
4. Callouts on future tactics
|
||||
-->
|
||||
@ -38,6 +38,66 @@ General Guidelines
|
||||
from the cmd line to run the test suite).
|
||||
- Add yourself to doc/contributors.rst :)
|
||||
|
||||
Authoring a Pull Request
|
||||
------------------------
|
||||
|
||||
**Our Pull Request Policy is based on this** `Code Review Developer Guide <https://google.github.io/eng-practices/review>`_
|
||||
|
||||
The expectation for any code author is to provide all the context needed in the space of a
|
||||
pull request for any engineer to feel equipped to review the code. Depending on the type of
|
||||
change, do your best to highlight important new functions or objects you’ve introduced in the
|
||||
code; think complex functions or new abstractions. Whilst it may seem like more work for you to
|
||||
adjust your pull request, the reality is your likelihood for getting review sooner shoots
|
||||
up.
|
||||
|
||||
**Self Review Guidelines to follow**
|
||||
|
||||
- If the PR is too large, split it if possible.
|
||||
- Use 250 LoC (excluding test data and config changes) as a rule-of-thumb.
|
||||
- Moving and changing code should be in separate PRs or commits.
|
||||
- Moving: Taking large code blobs and transplanting them to another file. There's generally no (or very little) actual code changed other than a cut and paste. It can even be extended to large deletions.
|
||||
- Changing: Adding code changes (be that refactors or functionality additions/subtractions).
|
||||
- These two, when mixed, can muddy understanding and sometimes make it harder for reviewers to keep track of things.
|
||||
- Prefer explaining with code comments instead of PR comments.
|
||||
|
||||
**Provide background**
|
||||
|
||||
- The PR description and linked tickets should answer the "what" and "why" of the change. The code change explains the "how".
|
||||
|
||||
**Follow the Template**
|
||||
|
||||
- Please do not deviate from the template we make; it is there for a lot of reasons. If it is a one line fix, we still need to have context on what and why it is needed.
|
||||
- If making a versioning change, please let that be known. See examples below:
|
||||
- ``versionadded:: 3.11``
|
||||
- ``versionchanged:: 3.5``
|
||||
|
||||
|
||||
**Pull Request Template Breakdown**
|
||||
|
||||
- **Github PR Title**
|
||||
- The PR Title format should always be ``[JIRA-ID] : Jira Title or Blurb Summary``.
|
||||
|
||||
- **JIRA LINK**
|
||||
- Convenient link to the associated JIRA ticket.
|
||||
|
||||
- **Summary**
|
||||
- Small blurb on why this is needed. The JIRA task should have the more in-depth description, but this should still, at a high level, give anyone looking an understanding of why the PR has been checked in.
|
||||
|
||||
- **Changes in this PR**
|
||||
- The explicit code changes that this PR is introducing. This should be more specific than just the task name. (Unless the task name is very clear).
|
||||
|
||||
- **Test Plan**
|
||||
- Everything needs a test description. Describe what you did to validate your changes actually worked; if you did nothing, then document you did not test it. Aim to make these steps reproducible by other engineers, specifically with your primary reviewer in mind.
|
||||
|
||||
- **Screenshots**
|
||||
- Any images that provide more context to the PR. Usually, these just coincide with the test plan.
|
||||
|
||||
- **Callouts or follow-up items**
|
||||
- This is a good place for identifying “to-dos” that you’ve placed in the code (Must have an accompanying JIRA Ticket).
|
||||
- Potential bugs that you are unsure how to test in the code.
|
||||
- Opinions you want to receive about your code.
|
||||
|
||||
|
||||
Running Linters
|
||||
---------------
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user