From ca6b346d6915656030f97f327e2ef42d1dbca47d Mon Sep 17 00:00:00 2001
From: Hanmin Qin <qinhanmin2005@sina.com>
Date: Fri, 20 Oct 2017 14:04:52 +0800
Subject: [PATCH] DOC Encourage contributors to use keywords to close issue
 automatically (#9954)

---
 CONTRIBUTING.md                 | 16 +++++++++++++---
 PULL_REQUEST_TEMPLATE.md        | 12 +++++++++---
 doc/developers/contributing.rst | 18 ++++++++++++++----
 3 files changed, 36 insertions(+), 10 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 2d40d72ea7..0481acf67f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -70,9 +70,19 @@ following rules before you submit a pull request:
    [Utilities for Developers](http://scikit-learn.org/dev/developers/utilities.html#developers-utils)
    page.
 
--  If your pull request addresses an issue, please use the pull request title
-   to describe the issue and mention the issue number in the pull request description. This will make sure a link back to the original issue is
-   created.
+-  Give your pull request a helpful title that summarises what your
+   contribution does. In some cases `Fix <ISSUE TITLE>` is enough.
+   `Fix #<ISSUE NUMBER>` is not enough.
+
+-  Often pull requests resolve one or more other issues (or pull requests).
+   If merging your pull request means that some other issues/PRs should
+   be closed, you should
+   [use keywords to create link to them](https://github.com/blog/1506-closing-issues-via-pull-requests/)
+   (e.g., `Fixes #1234`; multiple issues/PRs are allowed as long as each one
+   is preceded by a keyword). Upon merging, those issues/PRs will
+   automatically be closed by GitHub. If your pull request is simply related
+   to some other issues/PRs, create a link to them without using the keywords
+   (e.g., `See also #1234`).
 
 -  All public methods should have informative docstrings with sample
    usage presented as doctests when appropriate.
diff --git a/PULL_REQUEST_TEMPLATE.md b/PULL_REQUEST_TEMPLATE.md
index 3321b70332..9db6ade08b 100644
--- a/PULL_REQUEST_TEMPLATE.md
+++ b/PULL_REQUEST_TEMPLATE.md
@@ -1,9 +1,15 @@
 <!--
 Thanks for contributing a pull request! Please ensure you have taken a look at
-the contribution guidelines: https://github.com/scikit-learn/scikit-learn/blob/master/CONTRIBUTING.md#Contributing-Pull-Requests
+the contribution guidelines: https://github.com/scikit-learn/scikit-learn/blob/master/CONTRIBUTING.md#pull-request-checklist
+-->
+
+#### Reference Issues/PRs
+<!--
+Example: Fixes #1234. See also #3456.
+Please use keywords (e.g., Fixes) to create link to the issues or pull requests
+you resolved, so that they will automatically be closed when your pull request
+is merged. See https://github.com/blog/1506-closing-issues-via-pull-requests
 -->
-#### Reference Issue
-<!-- Example: Fixes #1234 -->
 
 
 #### What does this implement/fix? Explain your changes.
diff --git a/doc/developers/contributing.rst b/doc/developers/contributing.rst
index 5d8a95f17d..e236e936d0 100644
--- a/doc/developers/contributing.rst
+++ b/doc/developers/contributing.rst
@@ -218,10 +218,20 @@ rules before submitting a pull request:
       ``sklearn.utils`` submodule.  A list of utility routines available
       for developers can be found in the :ref:`developers-utils` page.
 
-    * If your pull request addresses an issue, please use the title to describe
-      the issue and mention the issue number in the pull request description to
-      ensure a link is created to the original issue.
-
+    * Give your pull request a helpful title that summarises what your
+      contribution does. In some cases "Fix <ISSUE TITLE>" is enough.
+      "Fix #<ISSUE NUMBER>" is not enough.
+
+    * Often pull requests resolve one or more other issues (or pull requests).
+      If merging your pull request means that some other issues/PRs should
+      be closed, you should `use keywords to create link to them
+      <https://github.com/blog/1506-closing-issues-via-pull-requests/>`_
+      (e.g., ``Fixes #1234``; multiple issues/PRs are allowed as long as each
+      one is preceded by a keyword). Upon merging, those issues/PRs will
+      automatically be closed by GitHub. If your pull request is simply
+      related to some other issues/PRs, create a link to them without using
+      the keywords (e.g., ``See also #1234``).
+    
     * All public methods should have informative docstrings with sample
       usage presented as doctests when appropriate.
 
-- 
GitLab