Merge pull request #16868 from QuLogic/release-guide

tacaswell · web-flow · commit 4a6c3b0914b2 · 2020-03-21T21:24:32.000-04:00
DOC: Update release guide
diff --git a/doc/devel/release_guide.rst b/doc/devel/release_guide.rst
@@ -25,7 +25,7 @@ All Releases
 Testing
 -------
 
-We use `travis-ci <https://travis-ci.org/matplotlib/matplotlib>`__ for
+We use `Travis CI <https://travis-ci.org/matplotlib/matplotlib>`__ for
 continuous integration.  When preparing for a release, the final
 tagged commit should be tested locally before it is uploaded::
 
@@ -34,7 +34,7 @@ tagged commit should be tested locally before it is uploaded::
 
 In addition the following test should be run and manually inspected::
 
-   python unit/memleak.py agg agg.pdf
+   python tools/memleak.py agg 1000 agg.pdf
 
 
 In addition the following should be run and manually inspected, but
@@ -51,42 +51,65 @@ GitHub Stats
 ------------
 
 
-We automatically extract GitHub issue, PRs, and authors from GitHub via the API.
-copy the current :file:`github_stats.rst` to :file:`github_stats_X.Y.Z.rst`.
+We automatically extract GitHub issue, PRs, and authors from GitHub via the
+API.  Copy the current :file:`doc/users/github_stats.rst` to
+:file:`doc/users/prev_whats_new/github_stats_X.Y.Z.rst`, changing the link
+target at the top of the file, and removing the "Previous GitHub Stats" section
+at the end.
 
-To re-generate the updated ::
+For example, when updating from v3.2.0 to v3.2.1::
 
-  python tools/github_stats.py --since-tag v2.2.0 --milestone=v3.0 --project 'matplotlib/matplotlib' --links > doc/users/github_stats.rst
+  cp doc/users/github_stats.rst doc/users/prev_whats_new/github_stats_3.2.0.rst
+  $EDITOR doc/users/prev_whats_new/github_stats_3.2.0.rst
+  # Change contents as noted above.
+  git add doc/users/prev_whats_new/github_stats_3.2.0.rst
 
-Review and commit changes.  Some issue/PR titles may not be valid rst (the most common issue is
-``*`` which is interpreted as unclosed markup).
+Then re-generate the updated stats::
 
-.. note
+  python tools/github_stats.py --since-tag v3.2.0 --milestone=v3.2.1 --project 'matplotlib/matplotlib' --links > doc/users/github_stats.rst
 
-   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.
+Review and commit changes.  Some issue/PR titles may not be valid reST (the
+most common issue is ``*`` which is interpreted as unclosed markup).
+
+.. note::
+
+   Make sure you authenticate against the GitHub API.  If you
+   do not you will get blocked by GitHub for going over the API rate
+   limits.  You can authenticate in one of two ways:
+
+   * using the ``keyring`` package; ``pip install keyring`` and then when
+     running the stats script, you will be prompted for user name and password,
+     that will be stored in your system keyring, or,
+   * using a personal access token; generate a new token `on this GitHub page
+     <https://github.com/settings/tokens>`__ with the ``repo:public_repo``
+     scope and place the token in :file:`~/.ghoauth`.
 
 
 .. _release_chkdocs:
 
 Update and Validate the Docs
 ----------------------------
 
-Merge the most recent 'doc' branch (``v3.0.2-doc``) into the branch you
+Merge ``*-doc`` branch
+^^^^^^^^^^^^^^^^^^^^^^
+
+Merge the most recent 'doc' branch (e.g., ``v3.2.0-doc``) 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.
+Update "What's New" and "API changes"
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Before tagging major and minor releases, the "what's new" and "API changes"
+listings should be updated.  This is not needed for micro releases.
 
-for the "what's new"
+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"
+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
@@ -95,13 +118,17 @@ Similarly for the "API changes"
 
 In both cases step 3 will have to be un-done right after the release.
 
+Verify that docs build
+^^^^^^^^^^^^^^^^^^^^^^
+
 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
-need to create a python2 environment with ``requests==2.9.0`` and linkchecker ::
+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 need to create a Python2 environment with
+``requests==2.9.0`` and linkchecker ::
 
   conda create -p /tmp/lnkchk python=2 requests==2.9.0
   source activate /tmp/lnkchk
@@ -110,8 +137,8 @@ need to create a python2 environment with ``requests==2.9.0`` and linkchecker ::
   linkchecker index.html --check-extern
   popd
 
-Address any issues which may arise.  The internal links are checked on travis, this should only
-flag failed external links.
+Address any issues which may arise.  The internal links are checked on Circle
+CI, this should only flag failed external links.
 
 .. _release_tag:
 
@@ -128,21 +155,21 @@ message ::
 
   git tag -a -s v2.0.0
 
-which will prompt you for your gpg key password and an annotation.
-For pre releases it is important to follow :pep:`440` so that the
-build artifacts will sort correctly in pypi.  Finally, push the tag to GitHub ::
-
-  git push -t DANGER v2.0.0
-
-Congratulations, the scariest part is done!
+which will prompt you for your GPG key password and an annotation.  For pre
+releases it is important to follow :pep:`440` so that the build artifacts will
+sort correctly in PyPI.
 
 To prevent issues with any down-stream builders which download the
 tarball from GitHub it is important to move all branches away from the commit
 with the tag [#]_::
 
   git commit --allow-empty
-  git push DANGER master
 
+Finally, push the tag to GitHub::
+
+  git push DANGER master v2.0.0
+
+Congratulations, the scariest part is done!
 
 .. [#] The tarball that is provided by GitHub is produced using `git
        archive <https://git-scm.com/docs/git-archive>`__.  We use
@@ -170,8 +197,8 @@ done for pre-releases)::
    git branch v2.0.0-doc
    git push DANGER v2.0.0-doc
 
-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)::
+and if this is a major or minor release, also create a bug-fix branch (a micro
+release will be cut from this branch)::
 
    git branch v2.0.x
 
@@ -192,31 +219,33 @@ Via the `GitHub UI
 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/citing.rst` with DOI link
-and commit to the VER-doc branch and push to GitHub ::
+For final releases, also get the DOI from `zenodo <https://zenodo.org/>`__
+(which will automatically produce one once the tag is pushed), add the DOI link
+to :file:`doc/citing.rst`, commit to the VER-doc branch and push to GitHub ::
 
   git checkout v2.0.0-doc
-  emacs doc/_templates/citing.html
+  $EDITOR doc/citing.html
   git push DANGER v2.0.0-doc:v2.0.0-doc
 
 .. _release_bld_bin:
 
 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 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).
+We distribute macOS, Windows, and many Linux wheels as well as a source tarball
+via PyPI.  Most builders should trigger automatically once the tag is pushed to
+GitHub:
+
+* Mac and manylinux wheels are built on Travis CI.  Builds are triggered by the
+  GitHub Action defined in :file:`.github/workflows/wheels.yml`, and wheels
+  will be available at the site defined in the `matplotlib-wheels repo
+  <https://github.com/MacPython/matplotlib-wheels>`__.
+* Windows wheels are built by Christoph Gohlke automatically and will be
+  `available at his site
+  <https://www.lfd.uci.edu/~gohlke/pythonlibs/#matplotlib>`__ once built.
+* 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::
 
@@ -231,7 +260,6 @@ If this is a final release the following downstream packagers should be contacte
 - Gentoo
 - Macports
 - Homebrew
-- Christoph Gohlke
 - Continuum
 - Enthought
 
@@ -240,8 +268,8 @@ 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
------------------------------------------
+Make distribution and upload to PyPI
+------------------------------------
 
 Once you have collected all of the wheels (expect this to take about a
 day), generate the tarball ::
@@ -284,13 +312,12 @@ The built documentation exists in the `matplotlib.github.com
 <https://github.com/matplotlib/matplotlib.github.com/>`__ repository.
 Pushing changes to master automatically updates the website.
 
-The documentation is organized by version.  At the root of the tree is
-always the documentation for the latest stable release.  Under that,
-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
-<https://matplotlib.org/devdocs>`__.
+The documentation is organized by version.  At the root of the tree is always
+the documentation for the latest stable release.  Under that, there are
+directories containing the documentation for older versions.  The documentation
+for current master is built on Circle CI and pushed to the `devdocs
+<https://github.com/matplotlib/devdocs/>`__ repository.  These are available at
+`matplotlib.org/devdocs <https://matplotlib.org/devdocs>`__.
 
 Assuming you have this repository checked out in the same directory as
 matplotlib ::
@@ -314,7 +341,7 @@ 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.
+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).
@@ -326,7 +353,7 @@ Announcing
 The final step is to announce the release to the world.  A short
 version of the release notes along with acknowledgments should be sent to
 
-- matplotlib-user@python.org
+- matplotlib-users@python.org
 - matplotlib-devel@python.org
 - matplotlib-announce@python.org
 
diff --git a/doc/devel/testing.rst b/doc/devel/testing.rst
@@ -194,7 +194,7 @@ are in ``test_mathtext.py``.
 Using Travis CI
 ---------------
 
-`Travis CI <https://travis-ci.org/>`_ is a hosted CI system "in the
+`Travis CI <https://travis-ci.com/>`_ is a hosted CI system "in the
 cloud".
 
 Travis is configured to receive notifications of new commits to GitHub
@@ -206,7 +206,7 @@ project.
 Travis CI is already enabled for the `main Matplotlib GitHub
 repository <https://github.com/matplotlib/matplotlib/>`_ -- for
 example, see `its Travis page
-<https://travis-ci.org/matplotlib/matplotlib>`_.
+<https://travis-ci.com/matplotlib/matplotlib>`_.
 
 If you want to enable Travis CI for your personal Matplotlib GitHub
 repo, simply enable the repo to use Travis CI in either the Travis CI
