@@ -213,6 +213,30 @@ should do to help ensure that your pull request is accepted.
213213 the other hand, fixes for typos and grammar errors in documents and
214214 docstrings are welcome.
215215
216+ #. **Follow best practices when creating the PR title and description. ** The
217+ pull requests title and description play a pivotal role in code review and
218+ issue resolution. It is the initial point of contact in a code review, and
219+ allows the code reviewer to quickly assess the issue. The suggested formatting
220+ of the title and description is
221+ **[type(optional) title: description (issue number)] ** where type is the label
222+ associated with the issue being resolved. Based on `Best practices for
223+ writing good pull request titles `_, a pull request title should be descriptive but
224+ to the point. It should establish a clear yet brief summary, so to allow the code
225+ reviewer to quickly assess the pull request.
226+ The description should explain what was changed in the pull request, why it exists,
227+ and explain the process of what was done in the pull request.
228+ Here is an example of a poor and revised pull request description:
229+ **Poor Pull Request: ** "update code" **Revised Pull Request: **
230+ "feat: add search functionality to user dashboard(closes #111)"
231+
232+ For more examples on writing a good pull request title, please take a look at
233+ `Best practices for
234+ writing good pull request titles `_
235+
236+ To read more on creating a descriptive pull request description, please review
237+ `Anatomy of a perfect pull request `_
238+
239+
216240#. **Be aware of backwards-compatibility considerations. ** While the core
217241 developer who eventually handles your pull request will make the final call on
218242 whether something is acceptable, thinking about backwards-compatibility early
@@ -606,3 +630,5 @@ accepts your pull request.
606630.. _issue tracker : https://github.com/python/cpython/issues
607631.. _Core Development Discourse category : https://discuss.python.org/c/core-dev/23
608632.. _Release Status : https://buildbot.python.org/all/#/release_status
633+ .. _Best practices for writing good pull request titles : https://graphite.dev/guides/best-pr-title-guidelines
634+ .. _Anatomy of a perfect pull request : https://opensource.com/article/18/6/anatomy-perfect-pull-request
0 commit comments