Skip to content

Commit

Permalink
Merge pull request #25235 from ksunden/release_guide
Browse files Browse the repository at this point in the history 
Update release guide instructions post v3.7.0
  • Loading branch information
@QuLogic
QuLogic authored Mar 15, 2023
2 parents ac32c78 + d6bfe99 commit 9700f74
Show file tree
Hide file tree
Showing 3 changed files with 121 additions and 36 deletions.
150 changes: 117 additions & 33 deletions doc/devel/release_guide.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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:

Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -225,25 +277,29 @@ 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

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:
Expand All @@ -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:
Expand Down Expand Up @@ -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

Expand All @@ -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"

Expand All @@ -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!
Expand All @@ -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
==========
Expand All @@ -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
Expand Down
5 changes: 3 additions & 2 deletions doc/users/release_notes.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -20,7 +22,6 @@ Version 3.7
github_stats.rst
prev_whats_new/github_stats_3.7.0.rst


Version 3.6
===========
.. toctree::
Expand Down
2 changes: 1 addition & 1 deletion tools/cache_zenodo_svg.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -149,4 +149,4 @@ def _get_xdg_cache_dir():
)
fout.write("\n\n")
fout.write("\n".join(footer))
fout.write('\n')
fout.write("\n")

0 comments on commit 9700f74

Please sign in to comment.