Update release instructions

dstansby · dstansby · commit 8c62234843b7 · 2019-06-25T17:14:14.000+01:00
diff --git a/changelog/README.rst b/changelog/README.rst
@@ -6,12 +6,8 @@ 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,
-for example::
-
-    Add support for Helioprojective coordinates in `sunpy.coordinates.frames`.
-
-Please try to use Sphinx intersphinx using backticks.
+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:
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
+  :folder:`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 :folder:`changelog/`.
 
 PR Review guidelines
 ====================
diff --git a/doc/devel/release_guide.rst b/doc/devel/release_guide.rst
@@ -71,29 +71,20 @@ 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
 
 Finally, make sure that the docs build cleanly ::
 
diff --git a/pyproject.toml b/pyproject.toml
@@ -2,7 +2,7 @@
 [tool.towncrier]
     package = "matplotlib"
     filename = "doc/CHANGELOG.rst"
-    directory = "doc/changelog/"
+    directory = "changelog/"
     issue_format = "`#{issue} <https://github.com/matplotlib/matplotlib/pull/{issue}>`__"
 
     [[tool.towncrier.type]]
