Release guide — Matplotlib 3.12.0.dev924+g1fedee5e3 documentation
Skip to main content Plot types User guide Tutorials Examples Reference Contribute Releases Gitter Discourse GitHub Release guide # This document is only relevant for Matplotlib release managers. A guide for developers who are doing a Matplotlib release. Versioning Scheme # Matplotlib follows the Intended Effort Versioning (EffVer) versioning scheme: macro.meso.micro . macro A release that we expect a large effort from our users to upgrade to.
The v1 to v2 transition included a complete overhaul of the default styles and the v2 to v3 transition involved dropping support for Python 2. Future macro versions would include changes of a comparable scale that can not be done incrementally in meso releases. meso A release that we expect some effort from our users to upgrade to. We target a Meso release every 6 months. These release are primarily intended to release new features to our users, however they also contain intentional feature deprecations and removals per our policy . micro A release that we expect users to require little to no effort to upgrade to.
Per our Backport strategy we only backport bug fixes to the maintenance branch. We expect minimal impact on users other than possibly breaking work arounds to a fixed bug or bugs being used as features . These are released as-needed, but typically every 1-2 months between meso releases. Create the release branch # Note This assumes that a read-only remote for the canonical repository is remote and a read/write remote is DANGER When a new meso 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 meso 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 meso 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 ). Close milestones for versions that are unlikely to be released, e.g. micro versions of older meso releases. Remilestone issues/PRs that are now untagged to the appropriate future release milestone. Create the milestone for the next-next meso release (i.e. v3.9.0 , as v3.8.0 should already exist).
While most active items should go in the next meso release, this milestone can help with longer term planning, especially around deprecation cycles. Testing # We use GitHub Actions for continuous integration. When preparing for a release, the final tagged commit should be tested locally before it is uploaded: pytest -n 8 . 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 . GitHub statistics # We automatically extract GitHub issue, PRs, and authors from GitHub via the API. To prepare this list: Archive the existing GitHub statistics page. Copy the current doc/release/github_stats.rst to doc/release/prev_whats_new/github_stats_ X . Y . Z .rst . Change the link target at the top of the file.
Remove the "Previous GitHub Stats" section at the end. For example, when updating from v3.7.0 to v3.7.1: cp doc/release/github_stats.rst doc/release/prev_whats_new/github_stats_3.7.0.rst $EDITOR doc/release/prev_whats_new/github_stats_3.7.0.rst # Change contents as noted above. git add doc/release/prev_whats_new/github_stats_3.7.0.rst Re-generate the updated stats: python tools/github_stats.py --since-tag v3.7.0 --milestone = v3.7.1 \ --project 'matplotlib/matplotlib' --links > doc/release/github_stats.rst Review and commit changes.
Some issue/PR titles may not be valid reST (the most common issue is * which is interpreted as unclosed markup). Also confirm that codespell does not find any issues. 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 with the repo:public_repo scope and place the token in ~/.ghoauth .
Update and validate the docs # Merge *-doc branch # 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 # When making macro or meso releases, update the supported versions in the Security Policy in SECURITY.md . For meso version release update the table in SECURITY.md to specify that the two most recent meso releases in the current macro version series are supported.
For a macro version release update the table in SECURITY.md to specify that the last meso version in the previous macro version series is still supported. Dropping support for the last version of a macro version series will be handled on an ad-hoc basis. Update release notes # What's new # Only needed for macro and meso releases. Bugfix releases should not have new features. Merge the contents of all the files in doc/release/next_whats_new/ into a single file doc/release/prev_whats_new/whats_new_ X .
Y .0.rst and delete the individual files. API changes # Primarily needed for macro and meso releases. We may sometimes have API changes in micro releases. Merge the contents of all the files in doc/api/next_api_changes/ into a single file doc/api/prev_api_changes/api_changes_ X . Y . Z .rst and delete the individual files. Release notes TOC # Update doc/release/release_notes.rst : For macro and meso releases add a new section X.Y === .. toctree :: :maxdepth: 1 prev_whats_new/whats_new_X.Y.0.rst ../api/prev_api_changes/api_changes_X.Y.0.rst prev_whats_new/github_stats_X.Y.0.rst For micro releases add the GitHub stats and (if present) the API changes to the existing X.Y section ../api/prev_api_changes/api_changes_X.Y.Z.rst prev_whats_new/github_stats_X.Y.Z.rst Update version switcher # The version switcher is populated from https://matplotlib.org/devdocs/_static/switcher.json .
Since it's always taken from devdocs, update the file doc/_static/switcher.json on the main branch through a regular PR: If a micro release, update the version from X . Y . Z-1 to X . Y . Z If a meso release X . Y .0 : update the dev entry to name: X . Y+1 (dev) update the stable entry to name: X . Y (stable) add a new entry for the previous stable ( name: X . Y-1 ). Once that PR is merged, the devdocs site will be updated automatically.
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: pip install linkchecker pushd doc/build/html linkchecker index.html --check-extern popd Address any issues which may arise. The internal links are checked on Circle CI, so this should only flag failed external links.
Cr
The rest of this page is on the live site.