Merge pull request #13421 from tacaswell/doc_release_notes

dstansby · web-flow · commit 7a7a40fc83c5 · 2019-02-19T12:20:01.000Z
DOC: update release guide
diff --git a/doc/api/api_changes.rst b/doc/api/api_changes.rst
@@ -17,23 +17,25 @@ This pages lists API changes for the most recent version of Matplotlib.
 
    api_changes_old
 
-..
 
-   .. note::
+.. note::
 
-     The list below is a table of contents of individual files from the 'next_api_changes' folder.
-     When a release is made
+   The list below is a table of contents of individual files from the
+   'next_api_changes' folder.
 
-       - The full text list below should be moved into its own file in 'prev_api_changes'
-       - All the files in 'next_api_changes' should be moved to the bottom of this page
-       - This note, and the toctree below should be commented out
+   When a release is made
 
+    - The full text list below should be moved into its own file in
+      'prev_api_changes'
+    - All the files in 'next_api_changes' should be moved to the bottom of this page
+    - This note, and the toctree below should be commented out
 
-   .. toctree::
-      :glob:
-      :maxdepth: 1
 
-      next_api_changes/*
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   next_api_changes/*
 
 
 API Changes for 3.0.1
diff --git a/doc/devel/release_guide.rst b/doc/devel/release_guide.rst
@@ -6,7 +6,16 @@
  Release Guide
 ===============
 
-A guide for developers who are doing a matplotlib release.
+
+.. admonition::  This document is only relevant for matplotlib release managers.
+
+   A guide for developers who are doing a matplotlib release.
+
+
+.. note::
+
+   This assumes that a read-only remote for the canonical repository is
+   ``remote`` and a read/write remote is ``DANGER``
 
 All Releases
 ============
@@ -43,18 +52,40 @@ We automatically extract GitHub issue, PRs, and authors from GitHub via the API:
 Review and commit changes.  Some issue/PR titles may not be valid rst (the most common issue is
 ``*`` which is interpreted as unclosed markup).
 
+.. note
+
+   Make sure you authenticate against the github API (either via
+   keyring or via putting an oauth token in :file:`~/.ghoauth`).  If you
+   do not you will get blocked by github for going over the API rate
+   limits.
+
 
 .. _release_chkdocs:
 
-Check Docs
-----------
+Update and Validate the Docs
+----------------------------
+
+Before tagging, update the "what's new" and "API changes" listings.
+
+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
 
-Before tagging, update the what's new listing in :file:`doc/users/whats_new.rst`
-by merging all files in :file:`doc/users/next_whats_new/` coherently. Also,
-temporarily comment out the include and toctree glob; re-instate these after a
-release. Finally, make sure that the docs build cleanly ::
+Similarly for the "API changes"
 
-  make -Cdoc O=-n$(nproc) html latexpdf
+ 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.
+
+Finally, make sure that the docs build cleanly ::
+
+  make -Cdoc O=-j$(nproc) html latexpdf
 
 After the docs are built, check that all of the links, internal and external, are still
 valid.  We use ``linkchecker`` for this, which has not been ported to python3 yet.  You will
@@ -130,21 +161,27 @@ and if this is a major or minor release, also create a bug-fix branch (a
 micro release will be cut off of this branch)::
 
    git branch v2.0.x
+
+On this branch un-comment the globs from :ref:`release_chkdocs`.  And then ::
+
    git push DANGER v2.0.x
 
 
 
+
 .. _release_DOI:
 
 Release Management / DOI
 ------------------------
 
-Via the GitHub UI (chase down link), turn the newly pushed tag into a
-release.  If this is a pre-release remember to mark it as such.
+Via the `GitHub UI
+<https://github.com/matplotlib/matplotlib/releases>`__, turn the newly
+pushed tag into a release.  If this is a pre-release remember to mark
+it as such.
 
 For final releases also get a DOI from `zenodo
-<https://zenodo.org/>`__ and edit :file:`doc/_templates/citing.html`
-with DOI link and commit to the VER-doc branch and push to GitHub ::
+<https://zenodo.org/>`__ and edit :file:`doc/citing.rst` with DOI link
+and commit to the VER-doc branch and push to GitHub ::
 
   git checkout v2.0.0-doc
   emacs doc/_templates/citing.html
@@ -158,12 +195,20 @@ Building binaries
 We distribute mac, windows, and many linux wheels as well as a source
 tarball via pypi.  Before uploading anything, contact the various
 builders.  Mac and manylinux wheels are built on travis .  You need to
-edit the :file:`.travis.yml` file and push to master of `the build
-project <https://github.com/MacPython/matplotlib-wheels>`__.
+edit the :file:`.travis.yml` file and push to the correct branch of
+`the build project
+<https://github.com/MacPython/matplotlib-wheels>`__.  For new minor
+versions create a new branch, for bug-fixes continue to use the current
+release branch.
+
+The auto-tick bot should open a pull request into the `conda-forge
+feedstock <https://github.com/conda-forge/matplotlib-feedstock>`__.
+Review and merge (if you have the power to).
+
+.. warning::
 
-Update the ``master`` branch (for pre-releases the ``devel`` branch)
-of the `conda-forge feedstock
-<https://github.com/conda-forge/matplotlib-feedstock>`__ via pull request.
+   Because this is automated, it is extremely important to bump all branches
+   away from the tag as discussed in :ref:`release_tag`.
 
 If this is a final release the following downstream packagers should be contacted:
 
@@ -179,12 +224,14 @@ If this is a final release the following downstream packagers should be contacte
 
 This can be done ahead of collecting all of the binaries and uploading to pypi.
 
+
 .. _release_upload_bin:
 
 make distribution and upload to pypi / SF
 -----------------------------------------
 
-Once you have collected all of the wheels, generate the tarball ::
+Once you have collected all of the wheels (expect this to take about a
+day), generate the tarball ::
 
   git checkout v2.0.0
   git clean -xfd
@@ -228,7 +275,7 @@ there are directories containing the documentation for older versions.
 The documentation for current master are built on travis and push to
 the `devdocs <https://github.com/matplotlib/devdocs/>`__ repository.
 These are available at `matplotlib.org/devdocs
-<http://matplotlib.org/devdocs>`__.
+<https://matplotlib.org/devdocs>`__.
 
 Assuming you have this repository checked out in the same directory as
 matplotlib ::
@@ -252,6 +299,8 @@ You will need to manually edit :file:`versions.html` to show the last
 
 Congratulations you have now done the third scariest part!
 
+If you have access, clear the cloudflare caches.
+
 It typically takes about 5-10 minutes for GitHub to process the push
 and update the live web page (remember to clear your browser cache).
 
@@ -267,9 +316,9 @@ version of the release notes along with acknowledgments should be sent to
 - matplotlib-announce@python.org
 
 For final releases announcements should also be sent to the
-numpy/scipy/jupyter mailing lists and python-announce.
+numpy/scipy/scikit-image mailing lists.
 
-In addition, announcements should be made on social networks (twitter,
-g+, FB).  For major release, `NumFOCUS <http://www.numfocus.org/>`__
-should be contacted for inclusion in their newsletter and maybe to
-have something posted on their blog.
+In addition, announcements should be made on social networks (twitter
+via the ``@matplotlib`` account, any other via personal accounts).
+`NumFOCUS <https://www.numfocus.org/>`__ should be contacted for
+inclusion in their newsletter.
