Merge pull request #27702 from tacaswell/pol/adopt_effver

GOV: adopt EffVer

Author: tacaswell

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

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": (

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
 ======================

doc/devel/api_changes.rst

@@ -54,7 +54,7 @@ prevents unexpected breaking of code.
 
 Rules
 ^^^^^
-- Deprecations are targeted at the next :ref:`minor release <pr-milestones>` (e.g. 3.x)
+- Deprecations are targeted at the next :ref:`meso release <pr-milestones>` (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

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
+<https://jacobtomlinson.dev/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
 <https://numpy.org/neps/nep-0029-deprecation_policy.html>`__.

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`

doc/devel/release_guide.rst

@@ -12,20 +12,51 @@ 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) <https://jacobtomlinson.dev/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 <deprecation-guidelines>`.
+
+*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 <https://xkcd.com/1172/>`_.
+
+  These are released as-needed, but typically every 1-2 months between meso releases.
 
 
 .. _release_feature_freeze:
 
 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,8 +200,8 @@ files.
 API changes
 ^^^^^^^^^^^
 
-*Primarily needed for major and minor releases. We may sometimes have API
-changes in bugfix releases.*
+*Primarily needed for macro and meso releases. We may sometimes have API
+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
@@ -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
 
@@ -193,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
@@ -206,8 +237,8 @@ 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 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}`).
 
@@ -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)
 
 

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

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.
 

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 minor 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 ""))

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
 

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 minor 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;
     }
@@ -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;

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].')