59 lines
2.8 KiB
ReStructuredText
59 lines
2.8 KiB
ReStructuredText
*************************
|
||
Pull Request Cover Letter
|
||
*************************
|
||
|
||
When opening up a pull request, please prepare a "cover letter" to place into
|
||
the "Description" field on Github. A good cover letter concisely answers as
|
||
many of the following questions as possible. Not all pull requests will have
|
||
answers to every one of these questions, which is okay!
|
||
|
||
* What JIRA ticket does this address (if any)? Please provide a link to the JIRA ticket
|
||
representing the bug you are fixing or the feature discussion you've already
|
||
had with the edX product owners.
|
||
|
||
* Who have you talked to at edX about this work? Design, architecture, previous PRs,
|
||
course project manager, IRC, mailing list, etc. Please include links to relevant
|
||
discussions.
|
||
|
||
* Why do you need this change? It's important for us to understand what problem your
|
||
change is trying to solve, so please describe fully why you feel this change is needed.
|
||
|
||
* What components are affected? (LMS, Studio, a specific app in the system, etc)
|
||
|
||
* What users are affected? For example, is this a new component intended for use
|
||
in just one course, or is this a system wide change affecting all edX students?
|
||
|
||
* Test instructions for manual testing. When it makes sense to do so, a good test
|
||
plan includes a tarball of a small test course that has a unit which triggers
|
||
the bug or illustrates the new feature. Another option would be to provide
|
||
explicit, numbered steps (ideally with screenshots!) to walk the reviewer
|
||
through your feature or fix.
|
||
|
||
* Please provide screenshots for all user-facing changes.
|
||
|
||
* Indicate the urgency of your request. If this is a pull request for a course
|
||
running or about to run on edx.org, we need to understand your time constraints.
|
||
Good pieces of information to provide are the course(s) that need this feature
|
||
and the date that the feature needed by.
|
||
|
||
* What are your concerns (the author’s) about the PR? Is there a corner case you
|
||
don't know how to address or some tests you aren't sure how to add? Please bring
|
||
these concerns up in your cover letter so we can help!
|
||
|
||
|
||
Example Of A Good PR Cover Letter
|
||
---------------------------------
|
||
|
||
`Pull Request 4675`_ is one of the first edX pull requests to include a cover
|
||
letter, and it is great! It clearly explains what the bug is, what system is
|
||
affected (just the LMS), includes a tarball of a course that demonstrates the
|
||
issue, and provides clear manual testing instructions.
|
||
|
||
`Pull Request 4983`_ is another great example. This pull request's cover letter
|
||
includes before and after screenshots, so the UX team can quickly understand
|
||
what changes were made and make suggestions. Further, the pull request indicates
|
||
how to manually test the feature and what date it is needed by.
|
||
|
||
.. _Pull Request 4675: https://github.com/edx/edx-platform/pull/4675
|
||
.. _Pull Request 4983: https://github.com/edx/edx-platform/pull/4983
|