matplotlib · dstansby · Jun 20, 2019 · Jun 25, 2019 · Jun 25, 2019 · Jun 25, 2019
diff --git a/changelog/14589.feature.rst b/changelog/14589.feature.rst
@@ -0,0 +1 @@
+The towncrier package is now used to generate changelogs
diff --git a/changelog/README.rst b/changelog/README.rst
@@ -0,0 +1,36 @@
+:orphan:
+
+Changelog
+=========
+
+This directory contains "news fragments" which are short files that contain a
+small **ReST**-formatted text that will be added to the next what's new page.
+
+Make sure to use full sentences with correct case and punctuation, and please
+try to use Sphinx intersphinx using backticks.
+
+Each file should be named like ``<PULL REQUEST>.<TYPE>.rst``, where
+``<PULL REQUEST>`` is a pull request number, and ``<TYPE>`` is one of:
+
+* ``breaking``: A change which requires users to change code and is not
+  backwards compatible. (Not to be used for removal of deprecated features.)
+* ``feature``: New user facing features and any new behavior.
+* ``removal``: Removal of a deprecated part of the API.
+* ``bugfix``: Any bug fixes that do not require users to change code.
+
+So for example: ``123.feature.rst``, ``456.api_change.rst``.
+
+If you are unsure what pull request type to use, don't hesitate to ask in your
+PR.
+
+Note that the ``towncrier`` tool will automatically reflow your text, so it
+will work best if you stick to a single paragraph, but multiple sentences and
+links are OK and encouraged.
+
+You can install ``towncrier`` and then run ``towncrier --draft`` if you want to
+get a preview of how your change will look in the final release notes.
+
+.. note::
+
+    This README was adapted from the pytest changelog readme under the terms of
+    the MIT licence.
diff --git a/doc/devel/coding_guide.rst b/doc/devel/coding_guide.rst
@@ -20,8 +20,8 @@ a case-by-case basis.
 Documentation
 -------------
 
-* Every new feature should be documented.  If it's a new module, don't
-  forget to add a new rst file to the API docs.
+* Every new feature should be documented. If it's a new module, don't
+  forget to add a new .rst file to the API docs.
 
 * Each high-level plotting function should have a small example in
   the `Example` section of the docstring.  This should be as simple as
@@ -32,11 +32,11 @@ Documentation
 
 * See :ref:`documenting-matplotlib` for our documentation style guide.
 
-* If your change is a major new feature, add an entry to
-  :file:`doc/users/whats_new.rst`.
+* If your change is a major new feature, add a changelog entry file to
+  :file:`changelog/`.
 
-* If you change the API in a backward-incompatible way, please
-  document it in :file:`doc/api/api_changes.rst`.
+* If you change the API in a backward-incompatible way, add a changelog
+  entry file to :file:`changelog/`.
 
 PR Review guidelines
 ====================

diff --git a/doc/devel/release_guide.rst b/doc/devel/release_guide.rst
@@ -71,29 +71,21 @@ Review and commit changes.  Some issue/PR titles may not be valid rst (the most
 
 .. _release_chkdocs:
 
-Update and Validate the Docs
+Update and validate the docs
 ----------------------------
 
-Merge the most recent 'doc' branch (``v3.0.2-doc``) into the branch you
+Merge the most recent 'doc' branch into the branch you
 are going to tag on and delete the doc branch on GitHub.
 
-Before tagging, update the "what's new" and "API changes" listings.
+Before tagging, update the changelog:
 
-for the "what's new"
-
- 1. copy the current content to a file in :file:`doc/users/prev_whats_new`
- 2. merge all of the files in :file:`doc/users/next_whats_new/` into
-    :file:`doc/users/whats_new.rst` and delete the individual files
- 3. comment out the next whats new glob at the top
-
-Similarly for the "API changes"
-
- 1. copy the current api changes to a file is :file:`doc/api/prev_api_changes`
- 2. merge all of the files in :file:`doc/api/next_api_changes/` into
-    :file:`doc//whats_new.rst`
- 3. comment out the next API changes at the top.
-
-In both cases step 3 will have to be un-done right after the release.
+1. Make sure you have `towncrier` installed
+2. Run ``towncrier --draft``, and make sure the output is sensible
+3. Run ``towncrier``
+4. Move the generated :file:`CHANGELOG.rst` file to
+   :file:`doc/users/prev_whats_new/whats_new_VERSION.rst`,
+   replacing `VERSION` with the current version number
+5. Update the file name in :file:`doc/users/whats_new.rst`
 
 Finally, make sure that the docs build cleanly ::
 

diff --git a/doc/users/next_whats_new/README.rst b/doc/users/next_whats_new/README.rst
diff --git a/requirements/doc/doc-requirements.txt b/requirements/doc/doc-requirements.txt
@@ -15,3 +15,4 @@ numpydoc>=0.8
 pillow>=3.4,!=5.4.0
 sphinx-gallery>=0.2
 sphinx-copybutton
+towncrier
diff --git a/towncrier.toml b/towncrier.toml
@@ -0,0 +1,26 @@
+
+[tool.towncrier]
+    package = "matplotlib"
+    filename = "doc/CHANGELOG.rst"
+    directory = "changelog/"
+    issue_format = "`#{issue} <https://github.com/matplotlib/matplotlib/pull/{issue}>`__"
+
+    [[tool.towncrier.type]]
+        directory = "breaking"
+        name = "Breaking API changes"
+        showcontent = true
+
+    [[tool.towncrier.type]]
+        directory = "bugfix"
+        name = "Bug fixes"
+        showcontent = true
+
+    [[tool.towncrier.type]]
+      directory = "removal"
+      name = "Removals"
+      showcontent = true
+
+    [[tool.towncrier.type]]
+      directory = "feature"
+      name = "New features"
+      showcontent = true
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		The towncrier package is now used to generate changelogs