diff --git a/doc/devel/release_guide.rst b/doc/devel/release_guide.rst
index 3f4b17d15231..fe7c1022e038 100644
--- a/doc/devel/release_guide.rst
+++ b/doc/devel/release_guide.rst
@@ -18,6 +18,47 @@ Release guide
``remote`` and a read/write remote is ``DANGER``
+.. _release_feature_freeze:
+
+Making the release branch
+=========================
+
+When a new minor release (vX.Y.0) is approaching, a new release branch must be made.
+When precisely this should happen is up to the release manager, but this point is where
+most new features intended for the minor release are merged and you are entering a
+feature freeze (i.e. newly implemented features will be going into vX.Y+1).
+This does not necessarily mean that no further changes will be made prior to release,
+just that those changes will be made using the backport system.
+
+For an upcoming ``v3.7.0`` release, first create the branch::
+
+ git switch main
+ git pull
+ git switch -c v3.7.x
+ git push DANGER v3.7.x
+
+Update the ``v3.7.0`` milestone so that the description reads::
+
+ New features and API changes
+
+ on-merge: backport to v3.7.x
+
+Micro versions should instead read::
+
+ Bugfixes and docstring changes
+
+ on-merge: backport to v3.7.x
+
+Check all active milestones for consistency. Older milestones should also backport
+to higher minor versions (e.g. ``v3.6.3`` and ``v3.6-doc`` should backport to both
+``v3.6.x`` and ``v3.7.x`` once the ``v3.7.x`` branch exists and while PR backports are
+still targeting ``v3.6.x``)
+
+Create the milestone for the next-next minor release (i.e. ``v3.9.0``, as ``v3.8.0``
+should already exist). While most active items should go in the next minor release,
+this milestone can help with longer term planning, especially around deprecation
+cycles.
+
.. _release-testing:
Testing
@@ -34,6 +75,14 @@ In addition the following test should be run and manually inspected::
python tools/memleak.py agg 1000 agg.pdf
+Run the User Acceptance Tests for the NBAgg and ipympl backends::
+
+ jupyter notebook lib/matplotlib/backends/web_backend/nbagg_uat.ipynb
+
+For ipympl, restart the kernel, add a cell for ``%matplotlib widget`` and do
+not run the cell with ``matplotlib.use('nbagg')``. Tests which check
+``connection_info``, use ``reshow``, or test the OO interface are not expected
+to work for ``ipympl``.
.. _release_ghstats:
@@ -50,16 +99,16 @@ prepare this list:
b. Change the link target at the top of the file.
c. Remove the "Previous GitHub Stats" section at the end.
- For example, when updating from v3.2.0 to v3.2.1::
+ For example, when updating from v3.7.0 to v3.7.1::
- 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
+ cp doc/users/github_stats.rst doc/users/prev_whats_new/github_stats_3.7.0.rst
+ $EDITOR doc/users/prev_whats_new/github_stats_3.7.0.rst
# Change contents as noted above.
- git add doc/users/prev_whats_new/github_stats_3.2.0.rst
+ git add doc/users/prev_whats_new/github_stats_3.7.0.rst
2. Re-generate the updated stats::
- python tools/github_stats.py --since-tag v3.2.0 --milestone=v3.2.1 \
+ python tools/github_stats.py --since-tag v3.7.0 --milestone=v3.7.1 \
--project 'matplotlib/matplotlib' --links > doc/users/github_stats.rst
3. Review and commit changes. Some issue/PR titles may not be valid reST (the most
@@ -87,7 +136,7 @@ Update and validate the docs
Merge ``*-doc`` branch
----------------------
-Merge the most recent 'doc' branch (e.g., ``v3.2.0-doc``) into the branch you
+Merge the most recent 'doc' branch (e.g., ``v3.7.0-doc``) into the branch you
are going to tag on and delete the doc branch on GitHub.
Update supported versions in Security Policy
@@ -193,7 +242,7 @@ notes in the commit message::
and then create a signed, annotated tag with the same text in the body message::
- git tag -a -s v2.0.0
+ git tag -a -s v3.7.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
@@ -206,9 +255,12 @@ it is important to move all branches away from the commit with the tag [#]_::
Finally, push the tag to GitHub::
- git push DANGER main v2.0.0
+ git push DANGER v3.7.x v3.7.0
Congratulations, the scariest part is done!
+This assumes the release branch has already been made.
+Usually this is done at the time of feature freeze for a minor release (which often
+coincides with the last patch release of the previous minor version)
.. [#] The tarball that is provided by GitHub is produced using `git archive`_.
We use setuptools_scm_ which uses a format string in
@@ -225,7 +277,7 @@ Congratulations, the scariest part is done!
To generate the file that GitHub does use::
- git archive v2.0.0 -o matplotlib-2.0.0.tar.gz --prefix=matplotlib-2.0.0/
+ git archive v3.7.0 -o matplotlib-3.7.0.tar.gz --prefix=matplotlib-3.7.0/
.. _git archive: https://git-scm.com/docs/git-archive
.. _setuptools_scm: https://github.com/pypa/setuptools_scm
@@ -233,17 +285,21 @@ Congratulations, the scariest part is done!
If this is a final release, also create a 'doc' branch (this is not
done for pre-releases)::
- git branch v2.0.0-doc
- git push DANGER v2.0.0-doc
+ git branch v3.7.0-doc
+ git push DANGER v3.7.0-doc
-and if this is a major or minor release, also create a bug-fix branch (a micro
-release will be cut from this branch)::
+Update (or create) the ``v3.7-doc`` milestone.
+The description should include the instruction for meeseeksmachine to backport changes
+with the ``v3.7-doc`` milestone to both the ``v3.7.x`` branch and the ``v3.7.0-doc`` branch::
- git branch v2.0.x
+ Documentation changes (.rst files and examples)
-On this branch un-comment the globs from :ref:`release_chkdocs`. And then ::
+ on-merge: backport to v3.7.x
+ on-merge: backport to v3.7.0-doc
- git push DANGER v2.0.x
+Check all active milestones for consistency. Older doc milestones should also backport to
+higher minor versions (e.g. ``v3.6-doc`` should backport to both ``v3.6.x`` and ``v3.7.x``
+if the ``v3.7.x`` branch exists)
.. _release_DOI:
@@ -259,16 +315,15 @@ automatically produce one once the tag is pushed). Add the DOI post-fix and vers
the dictionary in :file:`tools/cache_zenodo_svg.py` and run the script.
This will download the new SVG to :file:`doc/_static/zenodo_cache/{postfix}.svg` and
-edit :file:`doc/citing.rst`. Commit the new SVG, the change to
-:file:`tools/cache_zenodo_svg.py`, and the changes to :file:`doc/citing.rst` to the
-VER-doc branch and push to GitHub. ::
+edit :file:`doc/users/project/citing.rst`. Commit the new SVG, the change to
+:file:`tools/cache_zenodo_svg.py`, and the changes to :file:`doc/users/project/citing.rst`
+to the VER-doc branch and push to GitHub. ::
- git checkout v2.0.0-doc
+ git checkout v3.7.0-doc
$EDITOR tools/cache_zenodo_svg.py
python tools/cache_zenodo_svg.py
- $EDITOR doc/citing.html
git commit -a
- git push DANGER v2.0.0-doc:v2.0.0-doc
+ git push DANGER v3.7.0-doc:v3.7.0-doc
.. _release_bld_bin:
@@ -300,7 +355,7 @@ Make distribution and upload to PyPI
Once you have collected all of the wheels (expect this to take a few hours), generate
the tarball::
- git checkout v2.0.0
+ git checkout v3.7.0
git clean -xfd
python -m build --sdist
@@ -327,7 +382,7 @@ build the docs from the ``ver-doc`` branch. An easy way to arrange this is::
pip install matplotlib
pip install -r requirements/doc/doc-requirements.txt
- git checkout v2.0.0-doc
+ git checkout v3.7.0-doc
git clean -xfd
make -Cdoc O="-t release -j$(nproc)" html latexpdf LATEXMKOPTS="-silent -f"
@@ -347,22 +402,22 @@ Assuming you have this repository checked out in the same directory as
matplotlib ::
cd ../matplotlib.github.com
- cp -a ../matplotlib/doc/build/html 2.0.0
- rm 2.0.0/.buildinfo
- cp ../matplotlib/doc/build/latex/Matplotlib.pdf 2.0.0
+ cp -a ../matplotlib/doc/build/html 3.7.0
+ rm 3.7.0/.buildinfo
+ cp ../matplotlib/doc/build/latex/Matplotlib.pdf 3.7.0
which will copy the built docs over. If this is a final release, link the
``stable`` subdirectory to the newest version::
rm stable
- ln -s 2.0.0 stable
+ ln -s 3.7.0 stable
-You will need to manually edit :file:`versions.html` to show the last
-3 tagged versions. You will also need to edit :file:`sitemap.xml` to include
+You will need to manually edit :file:`versions.html` to show the released version.
+You will also need to edit :file:`sitemap.xml` to include
the newly released version. Now commit and push everything to GitHub ::
git add *
- git commit -a -m 'Updating docs for v2.0.0'
+ git commit -a -m 'Updating docs for v3.7.0'
git push DANGER main
Congratulations you have now done the third scariest part!
@@ -372,6 +427,33 @@ If you have access, clear the CloudFlare caches.
It typically takes about 5-10 minutes for the website to process the push and update the
live web page (remember to clear your browser cache).
+.. _release_merge_up:
+
+Merge up changes to main
+========================
+
+After a release is done, the changes from the release branch should be merged into the
+``main`` branch. This is primarily done so that the released tag is on the main branch
+so ``git describe`` (and thus ``setuptools-scm``) has the most current tag.
+Secondarily, changes made during release (including removing individualized release
+notes, fixing broken links, and updating the version switcher) are bubbled up to
+``main``.
+
+Git conflicts are very likely to arise, though aside from changes made directly to the
+release branch (mostly as part of the release), they should be relatively-easily resolved
+by using the version from ``main``. This is not a universal rule, and care should be
+taken to ensure correctness::
+
+ git switch main
+ git pull
+ git switch -c merge_up_v3.7.0
+ git merge v3.7.x
+ # resolve conflicts
+ git merge --continue
+
+Due to branch protections for the ``main`` branch, this is merged via a standard pull
+request, though the PR cleanliness status check is expected to fail. The PR should not
+be squashed because the intent is to merge the branch histories.
Announcing
==========
@@ -384,8 +466,10 @@ version of the release notes along with acknowledgments should be sent to
- matplotlib-announce@python.org
In addition, announcements should be made on social networks (e.g., Twitter via the
-``@matplotlib`` account, any other via personal accounts). `NumFOCUS
-<https://numfocus.org/>`__ should be contacted for inclusion in their newsletter.
+``@matplotlib`` account, any other via personal accounts).
+
+Add a release announcement to the ``mpl-brochure-site`` "News" section of
+``docs/body.html``, linking to the discourse page for the announcement.
Conda packages
diff --git a/doc/users/release_notes.rst b/doc/users/release_notes.rst
index 55264842ecd4..d5357e01e3d3 100644
--- a/doc/users/release_notes.rst
+++ b/doc/users/release_notes.rst
@@ -7,7 +7,9 @@ Release notes
=============
.. include from another document so that it's easy to exclude this for releases
-.. .. include:: release_notes_next.rst
+.. ifconfig:: releaselevel == 'dev'
+
+ .. include:: release_notes_next.rst
Version 3.7
@@ -20,7 +22,6 @@ Version 3.7
github_stats.rst
prev_whats_new/github_stats_3.7.0.rst
-
Version 3.6
===========
.. toctree::
diff --git a/tools/cache_zenodo_svg.py b/tools/cache_zenodo_svg.py
index 100572dc98f1..2a2a6cd85672 100644
--- a/tools/cache_zenodo_svg.py
+++ b/tools/cache_zenodo_svg.py
@@ -149,4 +149,4 @@ def _get_xdg_cache_dir():
)
fout.write("\n\n")
fout.write("\n".join(footer))
- fout.write('\n')
+ fout.write("\n")