From 12ae1b0c8b80c84b37b981860cd83bcba225028d Mon Sep 17 00:00:00 2001
From: Jeff <138259519+jdotc1@users.noreply.github.com>
Date: Thu, 22 Oct 2026 14:16:53 -0400
Subject: [PATCH 1/2] fix: make dim and spline deprecation warnings visible

---
 doc/whats-new.rst                        |  4 +++
 xarray/core/missing.py                   |  2 +-
 xarray/tests/test_deprecation_helpers.py | 38 +++++++++++++++++++++++-
 xarray/tests/test_interp.py              | 10 ++++++-
 xarray/tests/test_missing.py             |  5 +++-
 xarray/util/deprecation_helpers.py       |  3 +-
 6 files changed, 56 insertions(+), 6 deletions(-)

diff --git a/doc/whats-new.rst b/doc/whats-new.rst
index 21f3671188a..5d4ba0c2b4d 100644
--- a/doc/whats-new.rst
+++ b/doc/whats-new.rst
@@ -150,6 +150,10 @@ Breaking Changes
 
 Deprecations
 ~~~~~~~~~~~~
+- The deprecated ``dims=`` (or ``dimensions=``) argument renamed to ``dim=``
+  and ``interpolate_na(method="spline")`` now emit a ``FutureWarning`` instead
+  of a ``PendingDeprecationWarning``, so these warnings are visible by default
+  (:issue:`11721`).
 - Passing any argument after ``bins`` positionally to
   :py:meth:`Dataset.groupby_bins` and :py:meth:`DataArray.groupby_bins` is
   deprecated. It was meant to be deprecated in v2024.07.0, but the warning never
diff --git a/xarray/core/missing.py b/xarray/core/missing.py
index 0ab8b1116f9..2cf035fa2ae 100644
--- a/xarray/core/missing.py
+++ b/xarray/core/missing.py
@@ -521,7 +521,7 @@ def _get_interpolator(
             utils.emit_user_level_warning(
                 "The 1d SplineInterpolator class is performing an incorrect calculation and "
                 "is being deprecated. Please use `method=polynomial` for 1D Spline Interpolation.",
-                PendingDeprecationWarning,
+                FutureWarning,
             )
             if vectorizeable_only:
                 raise ValueError(f"{method} is not a vectorizeable interpolator. ")
diff --git a/xarray/tests/test_deprecation_helpers.py b/xarray/tests/test_deprecation_helpers.py
index 87ad8a6917d..f2ee0871cb8 100644
--- a/xarray/tests/test_deprecation_helpers.py
+++ b/xarray/tests/test_deprecation_helpers.py
@@ -1,6 +1,8 @@
+import warnings
+
 import pytest
 
-from xarray.util.deprecation_helpers import _deprecate_positional_args
+from xarray.util.deprecation_helpers import _deprecate_positional_args, deprecate_dims
 
 
 def test_deprecate_positional_args_warns_for_function():
@@ -138,3 +140,37 @@ class A5:
             @_deprecate_positional_args("v0.1")
             def __init__(self, a, *, b, c=3, **kwargs):
                 pass
+
+
+@pytest.mark.parametrize("old_name", ["dims", "dimensions"])
+def test_deprecate_dims_warns_and_forwards(old_name: str) -> None:
+    def func(*, dim: str, value: int) -> tuple[str, int]:
+        return dim, value
+
+    wrapped = (
+        deprecate_dims(func)
+        if old_name == "dims"
+        else deprecate_dims(func, old_name=old_name)
+    )
+    with pytest.warns(
+        FutureWarning, match=f"The `{old_name}` argument has been renamed to `dim`"
+    ):
+        result = wrapped(**{old_name: "x"}, value=42)
+    assert result == ("x", 42)
+
+
+@pytest.mark.parametrize("old_name", ["dims", "dimensions"])
+def test_deprecate_dims_canonical_dim_is_quiet(old_name: str) -> None:
+    def func(*, dim: str, value: int) -> tuple[str, int]:
+        return dim, value
+
+    wrapped = (
+        deprecate_dims(func)
+        if old_name == "dims"
+        else deprecate_dims(func, old_name=old_name)
+    )
+    with warnings.catch_warnings(record=True) as recorded:
+        warnings.simplefilter("always")
+        result = wrapped(dim="x", value=42)
+    assert result == ("x", 42)
+    assert not recorded
diff --git a/xarray/tests/test_interp.py b/xarray/tests/test_interp.py
index 8cd2cf6f040..3f74c816601 100644
--- a/xarray/tests/test_interp.py
+++ b/xarray/tests/test_interp.py
@@ -499,7 +499,15 @@ def test_errors(use_dask: bool) -> None:
         da = da.chunk()
 
     for method in ["spline"]:
-        with pytest.raises(ValueError), pytest.warns(PendingDeprecationWarning):
+        with (
+            pytest.raises(
+                ValueError, match="spline is not a vectorizeable interpolator"
+            ),
+            pytest.warns(
+                FutureWarning,
+                match="The 1d SplineInterpolator class is performing an incorrect calculation",
+            ),
+        ):
             da.interp(x=[0.5, 1.5], method=method)  # type: ignore[arg-type]
 
     # not sorted
diff --git a/xarray/tests/test_missing.py b/xarray/tests/test_missing.py
index 3751abce54d..021266dc890 100644
--- a/xarray/tests/test_missing.py
+++ b/xarray/tests/test_missing.py
@@ -143,7 +143,10 @@ def test_scipy_methods_function(method) -> None:
     # integration tests won't work.
     da, _ = make_interpolate_example_data((25, 25), 0.4, non_uniform=True)
     if method == "spline":
-        with pytest.warns(PendingDeprecationWarning):
+        with pytest.warns(
+            FutureWarning,
+            match="The 1d SplineInterpolator class is performing an incorrect calculation",
+        ):
             actual = da.interpolate_na(method=method, dim="time")
     else:
         actual = da.interpolate_na(method=method, dim="time")
diff --git a/xarray/util/deprecation_helpers.py b/xarray/util/deprecation_helpers.py
index 9ecf9557ef1..24ec9723811 100644
--- a/xarray/util/deprecation_helpers.py
+++ b/xarray/util/deprecation_helpers.py
@@ -138,8 +138,7 @@ def wrapper(*args, **kwargs):
                 f"The `{old_name}` argument has been renamed to `dim`, and will be removed "
                 "in the future. This renaming is taking place throughout xarray over the "
                 "next few releases.",
-                # Upgrade to `FutureWarning` in the future, when the renaming is complete.
-                PendingDeprecationWarning,
+                FutureWarning,
             )
             kwargs["dim"] = kwargs.pop(old_name)
         return func(*args, **kwargs)

From 1b0879b45132898f178c15cb8cd798e50f8f6d49 Mon Sep 17 00:00:00 2001
From: Jeff <138259519+jdotc1@users.noreply.github.com>
Date: Thu, 22 Oct 2026 17:45:38 -0400
Subject: [PATCH 2/2] DOC: preserve timestamp units in range example

---
 doc/internals/time-coding.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/doc/internals/time-coding.md b/doc/internals/time-coding.md
index bca49be9c2b..470640270ce 100644
--- a/doc/internals/time-coding.md
+++ b/doc/internals/time-coding.md
@@ -221,9 +221,9 @@ Depending on the internal resolution Timestamps can be represented in the range:
 
 ```{code-cell}
 for unit in ["s", "ms", "us", "ns"]:
-    print(
-        f"unit: {unit!r} time range ({pd.Timestamp(int64_min, unit=unit)}, {pd.Timestamp(int64_max, unit=unit)})"
-    )
+    start = pd.Timestamp(np.datetime64(int64_min, unit))
+    end = pd.Timestamp(np.datetime64(int64_max, unit))
+    print(f"unit: {unit!r} time range ({start}, {end})")
 ```
 
 Since relaxing the resolution, this enhances the range to several hundreds of thousands of centuries with microsecond representation. `NaT` will be at `np.iinfo("int64").min` for all of the different representations.