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:
Jib 2023-09-13 12:34:29 -04:00 committed by GitHub
parent 6787187f70
commit ee9cf10976
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 83 additions and 0 deletions

View 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
-->

View File

@ -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 youve 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 youve 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
---------------