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 -`__ 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")