fix(vim.deprecate): show deprecation warning in devel versions as well

Problem:

On devel(nightly) versions, deprecation warnings for hard-deprecated
features are not being displayed. E.g.,
  - to be removed in: 0.11
  - hard-deprecation since 0.10
  - soft-deprecation since 0.9

then 0.10-nightly (0.10.0-dev) versions as well as 0.10.0 (stable)
should display the deprecation warning message.

Solution:

Improve the code and logic on `vim.deprecate()`, and improve
test cases with mocked `vim.version()`.
This commit is contained in:
Jongwook Choi 2024-01-15 14:19:34 -05:00 committed by Lewis Russell
parent 9707363b09
commit 5a8fe0769c
2 changed files with 118 additions and 35 deletions

View File

@ -1033,21 +1033,44 @@ end
---
---@return string|nil # Deprecated message, or nil if no message was shown.
function vim.deprecate(name, alternative, version, plugin, backtrace)
vim.validate {
name = { name, 'string' },
alternative = { alternative, 'string', true },
version = { version, 'string', true },
plugin = { plugin, 'string', true },
}
plugin = plugin or 'Nvim'
-- 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
-- e.g., when planned to be removed in version = '0.12' (soft-deprecated since 0.10-dev),
-- show warnings since 0.11, including 0.11-dev (hard_deprecated_since = 0.11-dev).
if plugin == 'Nvim' then
local current_version = vim.version() ---@type Version
local removal_version = assert(vim.version.parse(version))
local is_hard_deprecated ---@type boolean
if removal_version.minor > 0 then
local hard_deprecated_since = assert(vim.version._version({
major = removal_version.major,
minor = removal_version.minor - 1,
patch = 0,
prerelease = 'dev', -- Show deprecation warnings in devel (nightly) version as well
}))
is_hard_deprecated = (current_version >= hard_deprecated_since)
else
-- Assume there will be no next minor version before bumping up the major version;
-- therefore we can always show a warning.
assert(removal_version.minor == 0, vim.inspect(removal_version))
is_hard_deprecated = true
end
if not is_hard_deprecated 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
msg = alternative and ('%s, use %s instead.'):format(msg, alternative) or (msg .. '.')
msg = ('%s%s\nThis feature will be removed in %s version %s'):format(
msg,
(plugin == 'Nvim' and ' :help deprecated' or ''),

View File

@ -128,8 +128,25 @@ describe('lua stdlib', function()
eq(1, fn.luaeval('vim.stricmp("\\0C\\0", "\\0B\\0")'))
end)
it('vim.deprecate', function()
local function test_vim_deprecate(current_version)
-- vim.deprecate(name, alternative, version, plugin, backtrace)
-- See MAINTAIN.md for the soft/hard deprecation policy
describe(('vim.deprecate [current_version = %s]'):format(current_version), function()
before_each(function()
-- mock vim.version() behavior, should be pinned for consistent testing
exec_lua(
[[
local current_version_mock = vim.version.parse(...)
getmetatable(vim.version).__call = function()
return current_version_mock
end
]],
current_version
)
end)
it('when plugin = nil', function()
eq(
dedent [[
foo.bar() is deprecated, use zub.wooo{ok=yay} instead. :help deprecated
@ -138,8 +155,31 @@ describe('lua stdlib', function()
)
-- Same message, skipped.
eq(vim.NIL, 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'))
-- Don't show error if not hard-deprecated (only soft-deprecated)
eq(
vim.NIL,
exec_lua('return vim.deprecate(...)', 'foo.baz()', 'foo.better_baz()', '0.12.0')
)
-- Show error if hard-deprecated
eq(
dedent [[
foo.hard_dep() is deprecated, use vim.new_api() instead. :help deprecated
This feature will be removed in Nvim version 0.11]],
exec_lua('return vim.deprecate(...)', 'foo.hard_dep()', 'vim.new_api()', '0.11')
)
-- To be deleted in the next major version (1.0)
eq(
dedent [[
foo.baz() is deprecated. :help deprecated
This feature will be removed in Nvim version 1.0]],
exec_lua [[ return vim.deprecate('foo.baz()', nil, '1.0') ]]
)
end)
it('when plugin is specified', function()
-- When `plugin` is specified, don't show ":help deprecated". #22235
eq(
dedent [[
@ -154,7 +194,27 @@ describe('lua stdlib', function()
false
)
)
-- plugins: no soft deprecation period
eq(
dedent [[
foo.bar() is deprecated, use zub.wooo{ok=yay} instead.
This feature will be removed in my-plugin.nvim version 0.11.0]],
exec_lua(
'return vim.deprecate(...)',
'foo.bar()',
'zub.wooo{ok=yay}',
'0.11.0',
'my-plugin.nvim',
false
)
)
end)
end)
end
test_vim_deprecate('0.10')
test_vim_deprecate('0.10-dev+g0000000')
it('vim.startswith', function()
eq(true, fn.luaeval('vim.startswith("123", "1")'))