From 960fdc775a88389d8b19389b8c74c98921b9acac Mon Sep 17 00:00:00 2001
From: "Justin M. Keyes" <justinkz@gmail.com>
Date: Thu, 17 Oct 2024 17:58:13 +0200
Subject: [PATCH] fix(lua): vim.deprecate does not support major>0

---
 MAINTAIN.md                      |  2 ++
 runtime/lua/vim/_editor.lua      | 18 ++++++++++++------
 test/functional/lua/vim_spec.lua | 15 ++++-----------
 3 files changed, 18 insertions(+), 17 deletions(-)

diff --git a/MAINTAIN.md b/MAINTAIN.md
index 5d046926c2..cd3dacb964 100644
--- a/MAINTAIN.md
+++ b/MAINTAIN.md
@@ -79,6 +79,8 @@ When a (non-experimental) feature is slated to be removed it should:
       `v0.10.0-dev-1957+gd676746c33` then use `0.12`.
     - For Vimscript features, use `v:lua.vim.deprecate()`. Use the same version
       as described for Lua features.
+    - `vim.deprecate(…, 'x.y.z')` where major version `x` is greater than the
+      current Nvim major version, is always treated as _soft_ deprecation.
 2. Be _hard_ deprecated in a following a release in which it was soft deprecated.
     - Use of the deprecated feature will still work but should issue a warning.
     - Features implemented in C will need bespoke implementations to communicate
diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua
index f0b8cf6a52..037cef9383 100644
--- a/runtime/lua/vim/_editor.lua
+++ b/runtime/lua/vim/_editor.lua
@@ -1149,16 +1149,22 @@ function vim.deprecate(name, alternative, version, plugin, backtrace)
   if plugin == 'Nvim' then
     require('vim.deprecated.health').add(name, version, traceback(), alternative)
 
-    -- Only issue warning if feature is hard-deprecated as specified by MAINTAIN.md.
-    -- Example: if removal_version is 0.12 (soft-deprecated since 0.10-dev), show warnings starting at
-    -- 0.11, including 0.11-dev
+    -- Show a warning only if feature is hard-deprecated (see MAINTAIN.md).
+    -- Example: if removal `version` is 0.12 (soft-deprecated since 0.10-dev), show warnings
+    -- starting at 0.11, including 0.11-dev.
     local major, minor = version:match('(%d+)%.(%d+)')
     major, minor = tonumber(major), tonumber(minor)
+    local nvim_major = 0 --- Current Nvim major version.
+
+    -- We can't "subtract" from a major version, so:
+    --  * Always treat `major > nvim_major` as soft-deprecation.
+    --  * Compare `minor - 1` if `major == nvim_major`.
+    if major > nvim_major then
+      return -- Always soft-deprecation (see MAINTAIN.md).
+    end
 
     local hard_deprecated_since = string.format('nvim-%d.%d', major, minor - 1)
-    -- Assume there will be no next minor version before bumping up the major version
-    local is_hard_deprecated = minor == 0 or vim.fn.has(hard_deprecated_since) == 1
-    if not is_hard_deprecated then
+    if major == nvim_major and vim.fn.has(hard_deprecated_since) == 0 then
       return
     end
 
diff --git a/test/functional/lua/vim_spec.lua b/test/functional/lua/vim_spec.lua
index 793cf7cfd7..ccb45a9d26 100644
--- a/test/functional/lua/vim_spec.lua
+++ b/test/functional/lua/vim_spec.lua
@@ -155,10 +155,10 @@ describe('lua stdlib', function()
       end)
 
       it('plugin=nil, no error if soft-deprecated', function()
-        eq(
-          vim.NIL,
-          exec_lua('return vim.deprecate(...)', 'foo.baz()', 'foo.better_baz()', '0.99.0')
-        )
+        eq(vim.NIL, exec_lua [[return vim.deprecate('old1', 'new1', '0.99.0')]])
+        -- Major version > current Nvim major is always "soft-deprecated".
+        -- XXX: This is also a reminder to update the hardcoded `nvim_major`, when Nvim reaches 1.0.
+        eq(vim.NIL, exec_lua [[return vim.deprecate('old2', 'new2', '1.0.0')]])
       end)
 
       it('plugin=nil, show error if hard-deprecated', function()
@@ -175,13 +175,6 @@ describe('lua stdlib', function()
         )
       end)
 
-      it('plugin=nil, to be deleted in the next major version (1.0)', function()
-        eq(
-          [[foo.baz() is deprecated. Run ":checkhealth vim.deprecated" for more information]],
-          exec_lua [[ return vim.deprecate('foo.baz()', nil, '1.0') ]]
-        )
-      end)
-
       it('plugin specified', function()
         -- When `plugin` is specified, don't show ":help deprecated". #22235
         eq(