From 493d5bde8cf050294ab5f33ba6f9873f77dee9fe Mon Sep 17 00:00:00 2001 From: Kyle Sunden Date: Thu, 16 Feb 2023 13:59:07 -0600 Subject: [PATCH 1/6] Update release guide instructions post v3.7.0 --- doc/devel/release_guide.rst | 34 +++++++++++++++++++++++++--------- tools/cache_zenodo_svg.py | 1 - 2 files changed, 25 insertions(+), 10 deletions(-) diff --git a/doc/devel/release_guide.rst b/doc/devel/release_guide.rst index 3f4b17d15231..e9943ca3419a 100644 --- a/doc/devel/release_guide.rst +++ b/doc/devel/release_guide.rst @@ -206,9 +206,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 v2.0.x v2.0.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 @@ -236,15 +239,29 @@ 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 from this branch):: +Update (or create) the ``v2.0-doc`` milestone. +The description should include the instruction for meeseeksmachine to backport changes +with the ``v2.0-doc`` milestone to both the ``v2.0.x`` branch and the ``v2.0.0-doc`` branch:: - git branch v2.0.x + Documentation changes (.rst files and examples) + + on-merge: backport to v2.0.x + on-merge: backport to v2.0.0-doc + +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) On this branch un-comment the globs from :ref:`release_chkdocs`. And then :: - git push DANGER v2.0.x + git push DANGER v2.1.x + +If this is the last micro release anticipated (or otherwise are entering feature +freeze for the next minor release), create a release branch for the next minor +release :: + git switch main + git branch v2.1.x .. _release_DOI: @@ -259,14 +276,13 @@ 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 $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 diff --git a/tools/cache_zenodo_svg.py b/tools/cache_zenodo_svg.py index 100572dc98f1..aca06544170c 100644 --- a/tools/cache_zenodo_svg.py +++ b/tools/cache_zenodo_svg.py @@ -149,4 +149,3 @@ def _get_xdg_cache_dir(): ) fout.write("\n\n") fout.write("\n".join(footer)) - fout.write('\n') From 7ee5fa7ca89ad3c322c398e3a0b9138d77123e9e Mon Sep 17 00:00:00 2001 From: Kyle Sunden Date: Wed, 22 Feb 2023 12:10:23 -0600 Subject: [PATCH 2/6] Reorder release branch creation and include merge up procedure --- doc/devel/release_guide.rst | 126 ++++++++++++++++++++++++++---------- doc/users/release_notes.rst | 5 +- tools/cache_zenodo_svg.py | 1 + 3 files changed, 96 insertions(+), 36 deletions(-) diff --git a/doc/devel/release_guide.rst b/doc/devel/release_guide.rst index e9943ca3419a..751381dfbe08 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 happens is up to the release manager, but at 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. + +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 @@ -50,16 +91,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 +128,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 +234,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,7 +247,7 @@ it is important to move all branches away from the commit with the tag [#]_:: Finally, push the tag to GitHub:: - git push DANGER v2.0.x 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. @@ -228,7 +269,7 @@ coincides with the last patch release of the previous minor version) 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 @@ -236,32 +277,22 @@ coincides with the last patch release of the previous minor version) 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 -Update (or create) the ``v2.0-doc`` milestone. +Update (or create) the ``v3.7-doc`` milestone. The description should include the instruction for meeseeksmachine to backport changes -with the ``v2.0-doc`` milestone to both the ``v2.0.x`` branch and the ``v2.0.0-doc`` branch:: +with the ``v3.7-doc`` milestone to both the ``v3.7.x`` branch and the ``v3.7.0-doc`` branch:: Documentation changes (.rst files and examples) - on-merge: backport to v2.0.x - on-merge: backport to v2.0.0-doc + on-merge: backport to v3.7.x + on-merge: backport to v3.7.0-doc 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) -On this branch un-comment the globs from :ref:`release_chkdocs`. And then :: - - git push DANGER v2.1.x - -If this is the last micro release anticipated (or otherwise are entering feature -freeze for the next minor release), create a release branch for the next minor -release :: - - git switch main - git branch v2.1.x .. _release_DOI: @@ -280,11 +311,11 @@ 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 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: @@ -316,7 +347,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 @@ -343,7 +374,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" @@ -363,22 +394,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 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! @@ -388,6 +419,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), should be relatively trivially 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 ========== 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 aca06544170c..2a2a6cd85672 100644 --- a/tools/cache_zenodo_svg.py +++ b/tools/cache_zenodo_svg.py @@ -149,3 +149,4 @@ def _get_xdg_cache_dir(): ) fout.write("\n\n") fout.write("\n".join(footer)) + fout.write("\n") From 42dcd32ff726349ccdd609431c9f87bc75bcede5 Mon Sep 17 00:00:00 2001 From: Kyle Sunden Date: Thu, 23 Feb 2023 21:16:07 -0600 Subject: [PATCH 3/6] Add UAT for notebook backends, remove contact numfocus --- doc/devel/release_guide.rst | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/doc/devel/release_guide.rst b/doc/devel/release_guide.rst index 751381dfbe08..738cd1a41d90 100644 --- a/doc/devel/release_guide.rst +++ b/doc/devel/release_guide.rst @@ -75,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 interfeace are not expected +to work for ``ipympl``. .. _release_ghstats: @@ -458,8 +466,7 @@ 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 -`__ should be contacted for inclusion in their newsletter. +``@matplotlib`` account, any other via personal accounts). Conda packages From b50cc04f1bc9ba8cfbe7f476608aa215a358ca8e Mon Sep 17 00:00:00 2001 From: Kyle Sunden Date: Fri, 3 Mar 2023 12:49:41 -0600 Subject: [PATCH 4/6] Spelling and grammar fixes Co-authored-by: Elliott Sales de Andrade --- doc/devel/release_guide.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/devel/release_guide.rst b/doc/devel/release_guide.rst index 738cd1a41d90..d5ff31658f9e 100644 --- a/doc/devel/release_guide.rst +++ b/doc/devel/release_guide.rst @@ -24,7 +24,7 @@ Making the release branch ========================= When a new minor release (vX.Y.0) is approaching, a new release branch must be made. -When precisely this happens is up to the release manager, but at this point is where +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, @@ -81,7 +81,7 @@ Run the User Acceptance Tests for the NBAgg and ipympl backends:: 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 interfeace are not expected +``connection_info``, use ``reshow``, or test the OO interface are not expected to work for ``ipympl``. .. _release_ghstats: @@ -440,7 +440,7 @@ 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), should be relatively trivially resolved +release branch (mostly as part of the release), they should be relatively trivially resolved by using the version from ``main``. This is not a universal rule, and care should be taken to ensure correctness:: From bc2f889ad929aa3e7fdb78245b3e72b19da13237 Mon Sep 17 00:00:00 2001 From: Kyle Sunden Date: Fri, 3 Mar 2023 13:12:43 -0600 Subject: [PATCH 5/6] Update announcement docs --- doc/devel/release_guide.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/doc/devel/release_guide.rst b/doc/devel/release_guide.rst index d5ff31658f9e..6ae97974cf09 100644 --- a/doc/devel/release_guide.rst +++ b/doc/devel/release_guide.rst @@ -412,8 +412,8 @@ which will copy the built docs over. If this is a final release, link the rm 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 * @@ -468,6 +468,9 @@ version of the release notes along with acknowledgments should be sent to In addition, announcements should be made on social networks (e.g., Twitter via the ``@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 ============== From d6bfe99e018d66c2d2c053b036aa1e2e031be2a8 Mon Sep 17 00:00:00 2001 From: Kyle Sunden Date: Mon, 13 Mar 2023 18:13:47 -0500 Subject: [PATCH 6/6] Apply suggestions from code review Co-authored-by: Elliott Sales de Andrade --- doc/devel/release_guide.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/devel/release_guide.rst b/doc/devel/release_guide.rst index 6ae97974cf09..fe7c1022e038 100644 --- a/doc/devel/release_guide.rst +++ b/doc/devel/release_guide.rst @@ -30,7 +30,7 @@ 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. -First create the branch :: +For an upcoming ``v3.7.0`` release, first create the branch:: git switch main git pull @@ -440,7 +440,7 @@ 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 trivially resolved +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::