From 95c628b68001dcaf8fe7f491c8a4ea240e4989f1 Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Thu, 25 Jan 2024 13:52:51 -0500 Subject: [PATCH 1/3] GOV: adopt EffVer EffVer very closely articulates what we are already doing. Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> --- doc/conf.py | 2 +- doc/devel/MEP/MEP13.rst | 2 +- doc/devel/api_changes.rst | 4 +- doc/devel/min_dep_policy.rst | 9 ++-- doc/devel/pr_guide.rst | 18 ++++---- doc/devel/release_guide.rst | 73 +++++++++++++++++++++--------- doc/devel/triage.rst | 2 +- lib/matplotlib/_api/deprecation.py | 2 +- src/ft2font_wrapper.cpp | 4 +- tools/github_stats.py | 2 +- 10 files changed, 75 insertions(+), 43 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index f975b8076044..3805facbfbcc 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -482,7 +482,7 @@ def js_tag_with_cache_busting(js): "switcher": { # Add a unique query to the switcher.json url. This will be ignored by # the server, but will be used as part of the key for caching by browsers - # so when we do a new minor release the switcher will update "promptly" on + # so when we do a new meso release the switcher will update "promptly" on # the stable and devdocs. "json_url": f"https://matplotlib.org/devdocs/_static/switcher.json?{SHA}", "version_match": ( diff --git a/doc/devel/MEP/MEP13.rst b/doc/devel/MEP/MEP13.rst index 58131a9a06fb..b8b80f281b6e 100644 --- a/doc/devel/MEP/MEP13.rst +++ b/doc/devel/MEP/MEP13.rst @@ -63,7 +63,7 @@ The following steps can be done simultaneously: 1, 2, and 3; 4 and 5; Only the following steps must be done in the same release: 4, 5, and 6. All other changes can be done in separate releases. 8 should -be done several major releases after everything else. +be done several macro releases after everything else. Backward compatibility ====================== diff --git a/doc/devel/api_changes.rst b/doc/devel/api_changes.rst index 52d52ecbd6da..b7d0a4b063ce 100644 --- a/doc/devel/api_changes.rst +++ b/doc/devel/api_changes.rst @@ -54,7 +54,7 @@ prevents unexpected breaking of code. Rules ^^^^^ -- Deprecations are targeted at the next :ref:`minor release ` (e.g. 3.x) +- Deprecations are targeted at the next :ref:`meso release ` (e.g. 3.x) - Deprecated API is generally removed (expired) two point-releases after introduction of the deprecation. Longer deprecations can be imposed by core developers on a case-by-case basis to give more time for the transition @@ -200,7 +200,7 @@ For example:: For classes and functions, the directive should be placed before the *Parameters* section. For parameters, the directive should be placed at the -end of the parameter description. The patch release version is omitted and +end of the parameter description. The micro release version is omitted and the directive should not be added to entire modules. Release notes diff --git a/doc/devel/min_dep_policy.rst b/doc/devel/min_dep_policy.rst index dd8e069f0b94..baf6db9811a8 100644 --- a/doc/devel/min_dep_policy.rst +++ b/doc/devel/min_dep_policy.rst @@ -4,10 +4,11 @@ Dependency version policy ========================= -For the purpose of this document, 'minor version' is in the sense of -SemVer (major, minor, patch) and includes both major and minor -releases. For projects that use date-based versioning, every release -is a 'minor version'. +For the purpose of this document, 'minor version' is in the sense of SemVer +(major, minor, patch) or 'meso version' in the sense of `EffVer +`_ (macro, meso, micro). It includes both +major/macro and minor/meso releases. For projects that use date-based +versioning, every release is a 'minor version'. Matplotlib follows `NEP 29 `__. diff --git a/doc/devel/pr_guide.rst b/doc/devel/pr_guide.rst index 257e218d8e1f..055998549e78 100644 --- a/doc/devel/pr_guide.rst +++ b/doc/devel/pr_guide.rst @@ -151,11 +151,11 @@ Milestones Set the milestone according to these guidelines: -* *New features and API changes* are milestoned for the next minor release +* *New features and API changes* are milestoned for the next meso release ``v3.N.0``. * *Bugfixes, tests for released code, and docstring changes* may be milestoned - for the next patch release ``v3.N.M``. + for the next micro release ``v3.N.M``. * *Documentation changes* (only .rst files and examples) may be milestoned ``v3.N-doc``. @@ -250,15 +250,15 @@ Current branches The current active branches are *main* - The current development version. Future minor releases (*v3.N.0*) will be + The current development version. Future meso (*v3.N.0*) or macro (*v4.0.0*) will be branched from this. *v3.N.x* - Maintenance branch for Matplotlib 3.N. Future patch releases will be - branched from this. + Maintenance branch for Matplotlib 3.N. Future micro releases will be + tagged from this. *v3.N.M-doc* - Documentation for the current release. On a patch release, this will be + Documentation for the current micro release. On a micro release, this will be replaced by a properly named branch for the new release. @@ -279,14 +279,14 @@ work. Backport strategy ----------------- -Backports to the patch release branch (*v3.N.x*) are the changes that will be +Backports to the micro release branch (*v3.N.x*) are the changes that will be included in the next patch (aka bug-fix) release. The goal of the patch releases is to fix bugs without adding any new regressions or behavior changes. We will always attempt to backport: - critical bug fixes (segfault, failure to import, things that the user cannot work around) -- fixes for regressions introduced in the last two minor releases +- fixes for regressions introduced in the last two meso releases and may attempt to backport fixes for regressions introduced in older releases. @@ -296,7 +296,7 @@ effort and risk of re-implementing the bug fix vs the severity of the bug. When in doubt, err on the side of not backporting. When backporting a Pull Request fails or is declined, re-milestone the original -PR to the next minor release and leave a comment explaining why. +PR to the next meso release and leave a comment explaining why. The only changes backported to the documentation branch (*v3.N.M-doc*) are changes to :file:`doc` or :file:`galleries`. Any changes to :file:`lib` diff --git a/doc/devel/release_guide.rst b/doc/devel/release_guide.rst index 4adc4546e879..ab917a35575e 100644 --- a/doc/devel/release_guide.rst +++ b/doc/devel/release_guide.rst @@ -12,10 +12,35 @@ Release guide A guide for developers who are doing a Matplotlib release. -.. note:: - This assumes that a read-only remote for the canonical repository is - ``remote`` and a read/write remote is ``DANGER`` +Versioning Scheme +================= + +Maplotlib 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 :ref:`our policy `. + +*micro* + A release that we expect users to require little to no effort to upgrade to. Per + our :ref:`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. .. _release_feature_freeze: @@ -23,9 +48,15 @@ Release guide Making the release branch ========================= -When a new minor release (vX.Y.0) is approaching, a new release branch must be made. +.. 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 minor release are merged and you are entering a +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. @@ -50,12 +81,12 @@ Micro versions should instead read:: 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 +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``) -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, +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. @@ -142,15 +173,15 @@ are going to tag on and delete the doc branch on GitHub. Update supported versions in Security Policy -------------------------------------------- -When making major or minor releases, update the supported versions in the Security +When making macro or meso releases, update the supported versions in the Security Policy in :file:`SECURITY.md`. -For minor version release update the table in :file:`SECURITY.md` to specify that the -two most recent minor releases in the current major version series are supported. +For meso version release update the table in :file:`SECURITY.md` to specify that the +two most recent meso releases in the current macro version series are supported. -For a major version release update the table in :file:`SECURITY.md` to specify that the -last minor version in the previous major version series is still supported. Dropping -support for the last version of a major version series will be handled on an ad-hoc +For a macro version release update the table in :file:`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 @@ -159,7 +190,7 @@ Update release notes What's new ^^^^^^^^^^ -*Only needed for major and minor releases. Bugfix releases should not have new +*Only needed for macro and meso releases. Bugfix releases should not have new features.* Merge the contents of all the files in :file:`doc/users/next_whats_new/` into a single @@ -169,7 +200,7 @@ files. API changes ^^^^^^^^^^^ -*Primarily needed for major and minor releases. We may sometimes have API +*Primarily needed for macro and meso releases. We may sometimes have API changes in bugfix releases.* Merge the contents of all the files in :file:`doc/api/next_api_changes/` into a single @@ -181,7 +212,7 @@ Release notes TOC Update :file:`doc/users/release_notes.rst`: -- For major and minor releases add a new section +- For macro and meso releases add a new section .. code:: rst @@ -207,7 +238,7 @@ Update version switcher Update ``doc/_static/switcher.json``: - If a bugfix release, :samp:`{X}.{Y}.{Z}`, no changes are needed. -- If a major release, :samp:`{X}.{Y}.0`, change the name of :samp:`name: {X}.{Y+1} +- If a macro release, :samp:`{X}.{Y}.0`, change the name of :samp:`name: {X}.{Y+1} (dev)` and :samp:`name: {X}.{Y} (stable)` as well as adding a new version for the previous stable (:samp:`name: {X}.{Y-1}`). @@ -259,8 +290,8 @@ Finally, push the tag to GitHub:: 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) +Usually this is done at the time of feature freeze for a meso release (which often +coincides with the last micro release of the previous meso version) .. [#] The tarball that is provided by GitHub is produced using `git archive`_. We use setuptools_scm_ which uses a format string in @@ -298,7 +329,7 @@ with the ``v3.7-doc`` milestone to both the ``v3.7.x`` branch and the ``v3.7.0-d 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`` +higher meso versions (e.g. ``v3.6-doc`` should backport to both ``v3.6.x`` and ``v3.7.x`` if the ``v3.7.x`` branch exists) diff --git a/doc/devel/triage.rst b/doc/devel/triage.rst index 1b2849738c9c..ca06fd515c79 100644 --- a/doc/devel/triage.rst +++ b/doc/devel/triage.rst @@ -160,7 +160,7 @@ The following workflow is a good way to approach issue triaging: While we strive for a bug-free library, regressions are the highest priority. If we have broken user-code that *used to* work, we should - fix that in the next patch release! + fix that in the next micro release! Try to determine when the regression happened by running the reproduction code against older versions of Matplotlib. This can diff --git a/lib/matplotlib/_api/deprecation.py b/lib/matplotlib/_api/deprecation.py index 7c304173b2e5..d937311603aa 100644 --- a/lib/matplotlib/_api/deprecation.py +++ b/lib/matplotlib/_api/deprecation.py @@ -29,7 +29,7 @@ def _generate_deprecation_warning( raise ValueError( "A pending deprecation cannot have a scheduled removal") else: - removal = f"in {removal}" if removal else "two minor releases later" + removal = f"in {removal}" if removal else "two meso releases later" if not message: message = ( ("The %(name)s %(obj_type)s" if obj_type else "%(name)s") diff --git a/src/ft2font_wrapper.cpp b/src/ft2font_wrapper.cpp index ef47a6574985..f010557e6341 100644 --- a/src/ft2font_wrapper.cpp +++ b/src/ft2font_wrapper.cpp @@ -75,7 +75,7 @@ static PyObject *PyFT2Image_draw_rect(PyFT2Image *self, PyObject *args) { char const* msg = "FT2Image.draw_rect is deprecated since Matplotlib 3.8 and will be removed " - "two minor releases later as it is not used in the library. If you rely on " + "two meso releases later as it is not used in the library. If you rely on " "it, please let us know."; if (PyErr_WarnEx(PyExc_DeprecationWarning, msg, 1)) { return NULL; @@ -841,7 +841,7 @@ static PyObject *PyFT2Font_get_xys(PyFT2Font *self, PyObject *args, PyObject *kw { char const* msg = "FT2Font.get_xys is deprecated since Matplotlib 3.8 and will be removed two " - "minor releases later as it is not used in the library. If you rely on it, " + "meso releases later as it is not used in the library. If you rely on it, " "please let us know."; if (PyErr_WarnEx(PyExc_DeprecationWarning, msg, 1)) { return NULL; diff --git a/tools/github_stats.py b/tools/github_stats.py index 54beac07ddf8..af0255fcefba 100755 --- a/tools/github_stats.py +++ b/tools/github_stats.py @@ -169,7 +169,7 @@ def report(issues, show_urls=False): parser.add_argument( '--since-tag', type=str, help='The git tag to use for the starting point ' - '(typically the last major release).') + '(typically the last macro release).') parser.add_argument( '--milestone', type=str, help='The GitHub milestone to use for filtering issues [optional].') From 53a2807e75a8b7285b3f5831d8cd5134fb65b9a6 Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Thu, 25 Jan 2024 17:30:02 -0500 Subject: [PATCH 2/3] DOC: also standardize "bugfix release" -> "micro release" --- doc/api/prev_api_changes/api_changes_1.3.x.rst | 2 +- doc/devel/release_guide.rst | 6 +++--- doc/users/prev_whats_new/whats_new_1.3.rst | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/api/prev_api_changes/api_changes_1.3.x.rst b/doc/api/prev_api_changes/api_changes_1.3.x.rst index 0aeb47815fcc..2601824ba7d1 100644 --- a/doc/api/prev_api_changes/api_changes_1.3.x.rst +++ b/doc/api/prev_api_changes/api_changes_1.3.x.rst @@ -7,7 +7,7 @@ API Changes in 1.3.x Changes in 1.3.1 ---------------- -It is rare that we make an API change in a bugfix release, however, +It is rare that we make an API change in a micro release, however, for 1.3.1 since 1.3.0 the following change was made: - ``text.Text.cached`` (used to cache font objects) has been made into a diff --git a/doc/devel/release_guide.rst b/doc/devel/release_guide.rst index ab917a35575e..fa2cd33731bd 100644 --- a/doc/devel/release_guide.rst +++ b/doc/devel/release_guide.rst @@ -201,7 +201,7 @@ API changes ^^^^^^^^^^^ *Primarily needed for macro and meso releases. We may sometimes have API -changes in bugfix releases.* +changes in micro releases.* Merge the contents of all the files in :file:`doc/api/next_api_changes/` into a single file :file:`doc/api/prev_api_changes/api_changes_{X}.{Y}.{Z}.rst` and delete the @@ -224,7 +224,7 @@ Update :file:`doc/users/release_notes.rst`: 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 bugfix releases add the GitHub stats and (if present) the API changes to +- For micro releases add the GitHub stats and (if present) the API changes to the existing X.Y section .. code:: rst @@ -237,7 +237,7 @@ Update version switcher Update ``doc/_static/switcher.json``: -- If a bugfix release, :samp:`{X}.{Y}.{Z}`, no changes are needed. +- If a micro release, :samp:`{X}.{Y}.{Z}`, no changes are needed. - If a macro release, :samp:`{X}.{Y}.0`, change the name of :samp:`name: {X}.{Y+1} (dev)` and :samp:`name: {X}.{Y} (stable)` as well as adding a new version for the previous stable (:samp:`name: {X}.{Y-1}`). diff --git a/doc/users/prev_whats_new/whats_new_1.3.rst b/doc/users/prev_whats_new/whats_new_1.3.rst index 855235069917..10811632c5c4 100644 --- a/doc/users/prev_whats_new/whats_new_1.3.rst +++ b/doc/users/prev_whats_new/whats_new_1.3.rst @@ -13,7 +13,7 @@ What's new in Matplotlib 1.3 (Aug 01, 2013) New in 1.3.1 ------------ -1.3.1 is a bugfix release, primarily dealing with improved setup and +1.3.1 is a micro release, primarily dealing with improved setup and handling of dependencies, and correcting and enhancing the documentation. From cce86903e044595992eb09012076a8fa9e6bf258 Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Tue, 6 Feb 2024 21:49:37 -0500 Subject: [PATCH 3/3] MNT: de-jargon hard-coded warning and deprecation decorator --- lib/matplotlib/_api/deprecation.py | 9 ++++++--- lib/matplotlib/tests/test_pyplot.py | 4 ++-- src/ft2font_wrapper.cpp | 4 ++-- 3 files changed, 10 insertions(+), 7 deletions(-) diff --git a/lib/matplotlib/_api/deprecation.py b/lib/matplotlib/_api/deprecation.py index d937311603aa..283a55f1beb0 100644 --- a/lib/matplotlib/_api/deprecation.py +++ b/lib/matplotlib/_api/deprecation.py @@ -29,14 +29,17 @@ def _generate_deprecation_warning( raise ValueError( "A pending deprecation cannot have a scheduled removal") else: - removal = f"in {removal}" if removal else "two meso releases later" + if not removal: + macro, meso, *_ = since.split('.') + removal = f'{macro}.{int(meso) + 2}' + removal = f"in {removal}" if not message: message = ( ("The %(name)s %(obj_type)s" if obj_type else "%(name)s") + (" will be deprecated in a future version" if pending else - (" was deprecated in Matplotlib %(since)s" - + (" and will be removed %(removal)s" if removal else ""))) + " was deprecated in Matplotlib %(since)s and will be removed %(removal)s" + ) + "." + (" Use %(alternative)s instead." if alternative else "") + (" %(addendum)s" if addendum else "")) diff --git a/lib/matplotlib/tests/test_pyplot.py b/lib/matplotlib/tests/test_pyplot.py index 6ebc24c46e29..a077aede8f8b 100644 --- a/lib/matplotlib/tests/test_pyplot.py +++ b/lib/matplotlib/tests/test_pyplot.py @@ -43,8 +43,8 @@ def test_pyplot_up_to_date(tmp_path): def test_copy_docstring_and_deprecators(recwarn): - @mpl._api.rename_parameter("(version)", "old", "new") - @mpl._api.make_keyword_only("(version)", "kwo") + @mpl._api.rename_parameter(mpl.__version__, "old", "new") + @mpl._api.make_keyword_only(mpl.__version__, "kwo") def func(new, kwo=None): pass diff --git a/src/ft2font_wrapper.cpp b/src/ft2font_wrapper.cpp index f010557e6341..1b03e5406147 100644 --- a/src/ft2font_wrapper.cpp +++ b/src/ft2font_wrapper.cpp @@ -75,8 +75,8 @@ static PyObject *PyFT2Image_draw_rect(PyFT2Image *self, PyObject *args) { char const* msg = "FT2Image.draw_rect is deprecated since Matplotlib 3.8 and will be removed " - "two meso releases later as it is not used in the library. If you rely on " - "it, please let us know."; + "in Matplotlib 3.10 releases later as it is not used in the library. " + "If you rely on it, please let us know."; if (PyErr_WarnEx(PyExc_DeprecationWarning, msg, 1)) { return NULL; }