From 8699b685c68081a4f6ddb136a780047492654909 Mon Sep 17 00:00:00 2001
From: "Paul \"LeoNerd\" Evans" <leonerd@leonerd.org.uk>
Date: Wed, 7 Feb 2024 17:19:26 +0000
Subject: [PATCH] Issue deprecation warnings on subsequent use VERSION
 declarations

---
 op.c                  |  5 +++++
 pod/perldiag.pod      | 24 ++++++++++++++++++++++++
 t/lib/warnings/op     |  6 ++++++
 t/lib/warnings/pp_ctl |  1 +
 4 files changed, 36 insertions(+)

diff --git a/op.c b/op.c
index d6caa2e7208ce..1a19b2f0b38c2 100644
--- a/op.c
+++ b/op.c
@@ -8030,6 +8030,11 @@ Perl_utilize(pTHX_ int aver, I32 floor, OP *version, OP *idop, OP *arg)
             /* downgrading from >= 5.11 to < 5.11 is now fatal */
             if (PL_prevailing_version >= SHORTVER(5, 11) && shortver < SHORTVER(5, 11))
                 croak("Downgrading a use VERSION declaration to below v5.11 is not permitted");
+
+            /* OK lets at least warn */
+            // TODO: do we set a sunset version?
+            ck_warner(packWARN(WARN_DEPRECATED),
+                    "use VERSION while another use VERSION is in scope is now deprecated");
         }
 
         /* If a version >= 5.11.0 is requested, strictures are on by default! */
diff --git a/pod/perldiag.pod b/pod/perldiag.pod
index 8a275e1b56194..cc29296819cc1 100644
--- a/pod/perldiag.pod
+++ b/pod/perldiag.pod
@@ -7852,6 +7852,30 @@ even if it requests a later version.
 subsequent one that calls for a Perl version of at least 5.39 while the first
 is visible.
 
+=item use VERSION while another use VERSION is in scope is now deprecated
+
+(W deprecated) Once you have a C<use VERSION> statement in scope, any other
+C<use VERSION> statement is now deprecated, due to the increasing complexity
+of swapping from one prevalent version to another.
+
+It is suggested that you do not try to mix multiple different version
+declarations within the same file as it leads to complex behaviours about the
+visibiity of features and builtin functions, as well as confusing human
+readers.
+
+If it is essential to have different C<use VERSION> declarations in different
+regions of the same file, you should surround each one by its own enclosing
+scope so the two do not mix.
+
+  {
+    use v5.20;
+    ...
+  }
+  {
+    use v5.36;
+    ...
+  }
+
 =item Use \x{...} for more than two hex characters in regex; marked by
 S<<-- HERE> in m/%s/
 
diff --git a/t/lib/warnings/op b/t/lib/warnings/op
index fe9bf8e19a9ab..0bb784905f572 100644
--- a/t/lib/warnings/op
+++ b/t/lib/warnings/op
@@ -2157,3 +2157,9 @@ c
 a
 d
 b
+########
+use warnings;
+use v5.12;
+use v5.20;
+EXPECT
+use VERSION while another use VERSION is in scope is now deprecated at - line 3.
diff --git a/t/lib/warnings/pp_ctl b/t/lib/warnings/pp_ctl
index 37dd4f1b7e9e0..b42c9ce3d2012 100644
--- a/t/lib/warnings/pp_ctl
+++ b/t/lib/warnings/pp_ctl
@@ -251,6 +251,7 @@ EXPECT
 use warnings;
 eval 'use 5.006; use 5.10.0';
 EXPECT
+use VERSION while another use VERSION is in scope is now deprecated at (eval 1) line 1.
 ########
 # SKIP ? !$Config{default_inc_includes_dot}
 # NAME check warning for do with no . in @INC