API: Add environment variable for behavior planned in a 2.0

The idea of the flag is not to allow to change it right now, since
there may be some things where that is hard to do in general, and
it doesn't seem relevant:  nobody is supposed to use it besides for
testing.

2 files changed, 18 insertions, 0 deletions

diff --git a/doc/release/numpy2_changes/README.md b/doc/release/numpy2_changes/README.md
new file mode 100644
index 000000000..fb59749a9
--- /dev/null
+++ b/doc/release/numpy2_changes/README.md
@@ -0,0 +1,4 @@
+Same as ``../upcoming_changes`` but for changes that currently
+are opt-in behind ``NPY_NUMPY_2_BEHAVIOR=1``.
+
+This is to get a start on release notes for such changes.
diff --git a/doc/source/reference/global_state.rst b/doc/source/reference/global_state.rst
index f5c96c355..a110ce7c1 100644
--- a/doc/source/reference/global_state.rst
+++ b/doc/source/reference/global_state.rst
@@ -95,3 +95,17 @@ memory allocation policy, the default will be to call ``free``. If
 ``NUMPY_WARN_IF_NO_MEM_POLICY`` is set to ``"1"``, a ``RuntimeWarning`` will
 be emitted. A better alternative is to use a ``PyCapsule`` with a deallocator
 and set the ``ndarray.base``.
+
+
+Testing planned future behavior
+===============================
+
+NumPy has some code paths which are planned to be activated in the future
+but are not yet the default behavior.
+You can try testing some of these which may be shipped with a new "major"
+release (NumPy 2.0) by setting an environment before importing NumPy:
+
+    NPY_NUMPY_2_BEHAVIOR=1
+
+By default this will also activate the :ref:`NEP 50 <NEP50>` related setting
+``NPY_PROMOTION_STATE`` (please see the NEP for details on this).