docs: add changelog for v2025.12 specification revision

PR-URL: #989
Reviewed-by: Evgeni Burovski

Author: kgryte

CHANGELOG.md

@@ -4,6 +4,77 @@
 
 This changelog is organized by specification version and notes all changes with respect to the previous version. Within the section for a specific version (e.g., v2022.12), separate sections are used for (a) changes to existing APIs and requirements, (b) new APIs and new requirements, and (c) errata.
 
+## v2025.12
+
+### Updates
+
+> Updates to existing APIs and requirements.
+
+#### Normative
+
+- Clarify guidance regarding device placement of returned output arrays ([gh-919](https://github.com/data-apis/array-api/pull/919))
+
+#### APIs
+
+- `__array_namespace__`: remove guidance recommending that the returned namespace only include those names which are part of this specification ([gh-931](https://github.com/data-apis/array-api/pull/931))
+- `__array_namespace_info__().default_device`: clarify support for `None` when the default device is not predictable ([gh-961](https://github.com/data-apis/array-api/pull/961))
+- `__setitem__`: specify type promotion behavior when the `value` argument is an array ([gh-920](https://github.com/data-apis/array-api/pull/920))
+- `asarray`: clarify that behavior when providing a nested sequence is unspecified ([gh-917](https://github.com/data-apis/array-api/pull/917))
+- `clip`: clarify type promotion behavior when providing scalar values for `min` and/or `max` arguments ([gh-926](https://github.com/data-apis/array-api/pull/926))
+- `expand_dims`: add support for specifying a tuple of axis positions ([gh-988](https://github.com/data-apis/array-api/pull/988))
+- `permute_dims`: add support for negative axes ([gh-980](https://github.com/data-apis/array-api/pull/980))
+
+##### Scalar Argument Support
+
+The following APIs were updated to support both scalar and array arguments for one or more arguments:
+
+- `searchsorted`: add scalar argument support ([gh-982](https://github.com/data-apis/array-api/pull/982))
+
+* * *
+
+### Additions
+
+> New APIs and requirements added to the specification.
+
+#### APIs
+
+The following APIs were added to the specification:
+
+- `broadcast_shapes`: broadcast one or more shapes against one another ([gh-983](https://github.com/data-apis/array-api/pull/983))
+- `isin`: test for each element in `x1` whether the element is in `x2` ([gh-959](https://github.com/data-apis/array-api/pull/959))
+
+#### Extensions
+
+The following APIs were added to optional specification extensions:
+
+- `linalg.eig`: return the eigenvalues and eigenvectors of a real or complex matrix ([gh-978](https://github.com/data-apis/array-api/pull/978))
+- `linalg.eigvals`: return the eigenvalues of a real or complex matrix ([gh-978](https://github.com/data-apis/array-api/pull/978))
+
+* * *
+
+### Breaking Changes
+
+The following is a list of breaking changes relative to the previous version of the specification:
+
+#### APIs
+
+- `__array_namespace_info__().devices`: return a tuple rather than a list ([gh-981](https://github.com/data-apis/array-api/pull/981))
+- `broadcast_arrays`: return a tuple rather than a list ([gh-981](https://github.com/data-apis/array-api/pull/981))
+- `meshgrid`: return a tuple rather than a list ([gh-981](https://github.com/data-apis/array-api/pull/981))
+
+* * *
+
+### Errata
+
+The following is a list of fixes and points of clarification with regard to the previous version of the specification:
+
+- `clip`: clarify type promotion behavior when providing scalar values for `min` and/or `max` arguments ([gh-926](https://github.com/data-apis/array-api/pull/926))
+- `linalg.eigh`: fix typing for output tuple ([gh-924](https://github.com/data-apis/array-api/pull/924))
+- `meshgrid`: fix typing for `indexing` argument ([gh-915](https://github.com/data-apis/array-api/pull/915))
+- `sqrt`: fix special case for complex-valued input ([gh-987](https://github.com/data-apis/array-api/pull/987))
+
+* * *
+
 ## v2024.12
 
 ### Updates

src/array_api_stubs/_draft/creation_functions.py

@@ -481,6 +481,9 @@ def meshgrid(*arrays: array, indexing: Literal["xy", "ij"] = "xy") -> Tuple[arra
 
     .. versionchanged:: 2022.12
        Added complex data type support.
+
+    .. versionchanged:: 2025.12
+       Changed the return value from a List to a Tuple.
     """
 
 

src/array_api_stubs/_draft/info.py

@@ -46,7 +46,7 @@ def __array_namespace_info__() -> Info:
       info.default_dtypes()
       # ...
 
-    .. versionadded: 2023.12
+    .. versionadded:: 2023.12
     """
 
 
@@ -66,7 +66,7 @@ def capabilities() -> Capabilities:
     Notes
     -----
 
-    .. versionadded: 2023.12
+    .. versionadded:: 2023.12
 
     .. versionchanged:: 2024.12
        Added support for querying the maximum number of supported dimensions.
@@ -87,7 +87,10 @@ def default_device() -> device:
 
     -   A conforming array library may return ``None`` if the default device is not predictable due to library specific device placement rules.
 
-    .. versionadded: 2023.12
+    .. versionadded:: 2023.12
+
+    .. versionchanged:: 2025.12
+       Clarified support for returning ``None`` when the default device is not predictable.
     """
 
 
@@ -120,7 +123,7 @@ def default_dtypes(
 
     -   Some array libraries have the concept of a device context manager, allowing library consumers to manage the current device context. When ``device`` is ``None``, libraries supporting a device context **must** return the default data types for the current device. For libraries without a context manager or supporting only a single device, those libraries **must** return the default data types for the default device.
 
-    .. versionadded: 2023.12
+    .. versionadded:: 2023.12
     """
 
 
@@ -170,7 +173,7 @@ def dtypes(
 
     -   Some array libraries have the concept of a device context manager, allowing library consumers to manage the current device context. When ``device`` is ``None``, libraries supporting a device context **must** return the supported data types for the current device. For libraries without a context manager or supporting only a single device, those libraries **must** return the supported data types for the default device.
 
-    .. versionadded: 2023.12
+    .. versionadded:: 2023.12
     """
 
 
@@ -191,5 +194,8 @@ def devices() -> Tuple[device, ...]:
     Notes
     -----
 
-    .. versionadded: 2023.12
+    .. versionadded:: 2023.12
+
+    .. versionchanged:: 2025.12
+       Changed the return value from a List to a Tuple.
     """

src/array_api_stubs/_draft/manipulation_functions.py

@@ -33,6 +33,12 @@ def broadcast_arrays(*arrays: array) -> Tuple[array, ...]:
     -------
     out: Tuple[array, ...]
         tuple of broadcasted arrays. Each array **must** have the same shape. Each array **must** have the same dtype as its corresponding input array.
+
+    Notes
+    -----
+
+    .. versionchanged:: 2025.12
+       Changed the return value from a List to a Tuple.
     """
 
 
@@ -143,6 +149,9 @@ def expand_dims(x: array, /, axis: Union[int, Tuple[int, ...]]) -> array:
         -   each entry of the tuple is normalized to positive axis positions according to the number of dimensions in the expanded output array.
         -   the normalized positive axis positions are sorted in ascending order.
         -   the normalized positive axis positions are unique.
+
+    .. versionchanged:: 2025.12
+       Added support for specifying a tuple of axis positions.
     """
 
 
@@ -209,6 +218,12 @@ def permute_dims(x: array, /, axes: Tuple[int, ...]) -> array:
     -------
     out: array
         an array containing the axes permutation. The returned array **must** have the same data type as ``x``.
+
+    Notes
+    -----
+
+    .. versionchanged:: 2025.12
+       Added support for negative axes.
     """
 
 

src/array_api_stubs/_draft/searching_functions.py

@@ -171,6 +171,9 @@ def searchsorted(
 
     .. versionchanged:: 2024.12
        Fixed incorrect boundary conditions.
+
+    .. versionchanged:: 2025.12
+       Added scalar argument support.
     """