From 0a598c13b1863ba1aff378027c4376e3ab7048ee Mon Sep 17 00:00:00 2001
From: dundargoc <gocdundar@gmail.com>
Date: Mon, 25 Dec 2023 16:31:38 +0100
Subject: [PATCH] feat(vim.deprecate): only issue warning if neovim version is
 high enough

As specified by MAINTAIN.md, features should be soft deprecated at first
(meaning no warnings) to give people a chance to adjust. The problem
with this approach is that deprecating a feature becomes harder than
usual as during the soft deprecation period you need to remember not to
issue a warning, and during the hard deprecation period you need to
remember to start issuing a warning.

This behavior is only enforced if the `plugin` parameter is `nil` as
plugins may not want this specific behavior.
---
 runtime/lua/vim/_editor.lua      | 12 ++++++++++++
 test/functional/lua/vim_spec.lua |  8 +++++---
 2 files changed, 17 insertions(+), 3 deletions(-)

diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua
index 0bb1becf58..dda89e2bdb 100644
--- a/runtime/lua/vim/_editor.lua
+++ b/runtime/lua/vim/_editor.lua
@@ -1019,6 +1019,18 @@ end
 ---
 ---@return string|nil # Deprecated message, or nil if no message was shown.
 function vim.deprecate(name, alternative, version, plugin, backtrace)
+  -- Only issue warning if feature is hard-deprecated as specified by MAINTAIN.md.
+  if plugin == nil then
+    local current_version = vim.version()
+    local deprecated_version = assert(vim.version.parse(version))
+    local soft_deprecated_version =
+      { deprecated_version.major, deprecated_version.minor - 1, deprecated_version.patch }
+    local deprecate = vim.version.lt(current_version, soft_deprecated_version)
+    if deprecate then
+      return
+    end
+  end
+
   local msg = ('%s is deprecated'):format(name)
   plugin = plugin or 'Nvim'
   msg = alternative and ('%s, use %s instead.'):format(msg, alternative) or msg
diff --git a/test/functional/lua/vim_spec.lua b/test/functional/lua/vim_spec.lua
index 509958bbde..e017ea7670 100644
--- a/test/functional/lua/vim_spec.lua
+++ b/test/functional/lua/vim_spec.lua
@@ -132,11 +132,13 @@ describe('lua stdlib', function()
     -- vim.deprecate(name, alternative, version, plugin, backtrace)
     eq(dedent[[
       foo.bar() is deprecated, use zub.wooo{ok=yay} instead. :help deprecated
-      This feature will be removed in Nvim version 2.17]],
-      exec_lua('return vim.deprecate(...)', 'foo.bar()', 'zub.wooo{ok=yay}', '2.17'))
+      This feature will be removed in Nvim version 0.10]],
+      exec_lua('return vim.deprecate(...)', 'foo.bar()', 'zub.wooo{ok=yay}', '0.10'))
     -- Same message, skipped.
     eq(vim.NIL,
-      exec_lua('return vim.deprecate(...)', 'foo.bar()', 'zub.wooo{ok=yay}', '2.17'))
+      exec_lua('return vim.deprecate(...)', 'foo.bar()', 'zub.wooo{ok=yay}', '0.10'))
+    -- Don't show error if not hard deprecated
+    eq(vim.NIL, exec_lua('return vim.deprecate(...)', 'foo.bar()', 'nil', '5000.0.0'))
     -- When `plugin` is specified, don't show ":help deprecated". #22235
     eq(dedent[[
       foo.bar() is deprecated, use zub.wooo{ok=yay} instead.