3.3. Pull Request Cover Letter¶

For features with user-facing impact, please make sure you’ve also read the guidelines for Contributing to the Documentation for Your Open Source Feature.

When opening up a pull request, a cover letter template will be prepopulated for you. It has some items marked with TODO. These are indications of actions that you should take before (or as part of) submitting the pull request, and then can be deleted.

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, community discussions, 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!