Document Gaëtan's new script to prefill a changelog entry.

1 files changed, 13 insertions, 14 deletions

diff --git a/doc/changelog/README.md b/doc/changelog/README.md
index 2891eb207e..3e0970a656 100644
--- a/doc/changelog/README.md
+++ b/doc/changelog/README.md
@@ -7,25 +7,28 @@ otherwise important infrastructure changes, and important bug fixes
 should get a changelog entry.
 
 Compatibility-breaking changes should always get a changelog entry,
-which should explain what compatibility-breakage is to expect.
+which should explain what compatibility breakage is to expect.
 
 Pull requests changing the ML API in significant ways should add an
 entry in [`dev/doc/changes.md`](../../dev/doc/changes.md).
 
 ## How to add an entry? ##
 
-You should create a file in one of the sub-directories. The name of
-the file should be `NNNNN-identifier.rst` where `NNNNN` is the number
-of the pull request on five digits and `identifier` is whatever you
-want.
-
-This file should use the same format as the reference manual (as it
-will be copied in there). You may reference the documentation you just
-added with `:ref:`, `:tacn:`, `:cmd:`, `:opt:`, `:token:`, etc. See
+Run `./dev/tools/make-changelog.sh`: it will ask you for your PR
+number, and to choose among the predefined categories.  Afterward,
+fill in the automatically generated entry with a short description of
+your change (which should describe any compatibility issues in
+particular).  You may also add a reference to the relevant fixed
+issue, and credit reviewers, co-authors, and anyone who helped advance
+the PR.
+
+The format for changelog entries is the same as in the reference
+manual.  In particular, you may reference the documentation you just
+added with `:ref:`, `:tacn:`, `:cmd:`, `:opt:`, `:token:`, etc.  See
 the [documentation of the Sphinx format](../sphinx/README.rst) of the
 manual for details.
 
-The entry should be written using the following structure:
+Here is a summary of the structure of a changelog entry:
 
 ``` rst
 - Description of the changes, with possible link to
@@ -35,7 +38,3 @@ The entry should be written using the following structure:
   [ and `#ISSUE2 <https://github.com/coq/coq/issues/ISSUE2>`_],]
   by Full Name[, with help / review of Full Name]).
 ```
-
-The description should be kept rather short and the only additional
-required meta-information are the link to the pull request and the
-full name of the author.