Document auto-closing keywords for PRs. (#855)

* Document auto-closing keywords for PRs.

* Bedevere now adds the issue number in the body.

* Apply suggestions from code review

Co-authored-by: CAM Gerlach <[email protected]>

* Add a new entry about linking to issues/PRs.

* Make sentence more explicit.

Co-authored-by: Alex Waygood <[email protected]>

Co-authored-by: CAM Gerlach <[email protected]>
Co-authored-by: Alex Waygood <[email protected]>

Author: 3 people

getting-started/git-boot-camp.rst

@@ -283,6 +283,28 @@ Creating a Pull Request
 
 6. Press the ``Create pull request`` button.
 
+You should include the issue number in the title of the PR,
+in the format ``gh-NNNNN: <PR Title>``.
+
+Linking to Issues and Pull Requests
+-----------------------------------
+
+You can link to issues and pull requests using ``gh-NNNNN`` (this form is
+preferred over ``#NNNNN``).  If the reference appears in a list, the link
+will be expanded to show the status and title of the issue/PR.
+
+When you create a PR that includes ``gh-NNNNN`` in the title, `bedevere`_
+will automatically add a link to the issue in the first message.
+
+In addition, pull requests support `special keywords`_ that can be used to
+link to an issue and automatically close it when the PR is merged.
+However, issues often require multiple PRs before they can be closed (e.g.
+backports to other branches), so this features is only useful if
+you know for sure that a single PR is enough to address and close the issue.
+
+.. _bedevere: https://github.com/python/bedevere
+.. _special keywords: https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword
+
 Updating your CPython Fork
 --------------------------