Breaking Changes (Please Subscribe)

[ckipp01]

When I first started nvim-metals I had never touched Lua before. I made some newbie mistakes, which is to be expected when getting started with a language. While I still consider myself pretty amateur with Lua, I'm at least seeing some of the mistakes I made early on which are now pain points as I've tried to add tests. With that in mind, I don't take breaking changes lightly, and I'm more than aware of how annoying they are for users. With that being said, there will be times I'll need to make them, and I'd like them to be as painless as possible. So there are a few things you can do to help ensure they are indeed less painful.

1. Subscribe to this discussion. I'll only post here when I'm breaking something with details on what I'm changing and how you'll need to account for it in your config.
2. If you use packer.nvim you'll get a warning when you update nvim-metals when a breaking change occurs. This is because there will be a breaking change in the commit message which triggers packer to show you the commit. Look at the commit message, it will contain info on what is breaking.

Cheers

[ckipp01]

#255 introduces a breaking change in the way that you need to use metals.setup.bare_config. In the past this was just a table that you'd access to use as your base config. This is now a function that returns the same bare config, but avoids mutating that table inside nvim-metals.

How to Migrate

In your config wherever you access the bare_config you now simply call it.

- Metals_config = require("metals").bare_config
+ Metals_config = require("metals").bare_config()

If you don't make this change, you'll end up seeing the following error:

Error while calling lua chunk: /Users/ckipp/.config/nvim/lua/settings/lsp.lua:29: attempt to index global 'Metals_config' (a function value)

[ckipp01]

#276 deprecates the g["metals_server_version"] = "0.10.9+120-ff0815ae-SNAPSHOT" way of setting the server version with a global options. This will be fully removed after a couple weeks. The preferred way of setting this is via the settings table in your config. For example:

Metals_config = require("metals").bare_config()

Metals_config.settings = {
  serverVersion = "0.10.9+126-14672630-SNAPSHOT"
}

This also applies to the g["metals_server_org"] option, which was replaced with serverOrg in the settings table. Eventually all the global options will be replaced with settings like this (#234).

NOTE: As an aside this change also introduces a new way to keep up to date with the latest snapshot version without needing to go look on the website. If you use SNAPSHOT as the serverVersion it will automatically pull the latest snapshot from the maven-metadata.xml file and use that when you do a metals install or update.

[ckipp01]

On a related note to these changes, now all options are now replaced with their setting equivalents that can all be set in the settings table like the serverVersion example up above. Below you'll find a mapping of the previous options and their new setting counterparts

Old Option Name	New Setting Name
metals_server_version	serverVersions
metals_server_org	serverOrg
metals_decoration_color	decorationColor
metals_disabled_mode	disabledMode
metals_use_global_executable	useGlobalExecutable

Again, these are deprecated at the moment and in a couple weeks they will be fully removed.

[ckipp01]

These are now fully removed.

[ckipp01]

TLDR

Update to v.0.6.0

Longer explanation

As of #283 the minimum version of Neovim that is required in v0.6.0. You should be able to just update and be set unless you had customer handlers that you were overriding in nvim-metals. If that's the case, please pay attention to the new handler signature in v0.6.0:

function(err, result, context, config)

The other feature that we make use of is the vim.ui.* api that is now available. NOTE: that there are cases where we were unable to use this where there was a return necessary, like in LSP requests that come from the server that need a response. Since vim.ui.* is callback based and there is no guarantee if the various plugin implementations are async or not, it's not safe to use in those situations.

As always, don't hesitate to reach out if you hit on something.

[ckipp01]

As of #290 the open_all_diagnostics() function has been removed. This method was added in order to provide an easy way to get all your workspace diagnostics and be able to have the errors on top. Since the new diagnostics api, this is all pretty much possible with the built-in diagnostics functions. For example, I've replaced my open_all_diagnostics usage with the following:

vim.diagnostic.setqflist() // This open the qf with all workspace diagnostics
vim.diagnostic.setqflist({severity = "E"}) // same as the above, but only errors
vim.diagnostic.setqflist({severity = "W"}) // same as the above, but with only warnings

[ckipp01]

With the recent release of Neovim 0.7.0 there are some new changes to various apis that make doing things like defining autocmds much cleaner. Therefore I've gone ahead and started using these in a recent commit to nvim-metals. You can see the details here: #369.

While there should be nothing you actually need to change in your config or anything, I marked as a breaking change because it will force you to ensure you have the newest Neovim installed. Updating should be all you need to do. Note that I've also updated the docs to reference the new style of autocmds to setup nvim-metals. For example, in the past you probably had something like this.

vim.cmd [[augroup lsp]]
vim.cmd [[au!]]
vim.cmd [[au FileType java,scala,sbt lua require("metals").initialize_or_attach({})]]
vim.cmd [[augroup end]]

Whereas the new api will allow you to instead do something like this:

local nvim_metals_group = vim.api.nvim_create_augroup("nvim-metals", { clear = true })
vim.api.nvim_create_autocmd("FileType", {
  pattern = { "scala", "sbt", "java" },
  callback = function()
    require("metals").initialize_or_attach({})
  end,
  group = nvim_metals_group,
})

While the old style will still work, I'd recommend switching to the new. However the internal autocmds that nvim-metals sets up will use the new, so that will throw an error if you're on a version of Neovim < 0.7.0.

[ckipp01]

So a very small breaking change in the lua API for require("metals").toggle_logs(direction). In the past this function could take a direction to help facilitate whether the toggle of logs would be a :sp or :vsp. Recently I used the :LspLog functionality of nvim-lspconfig and I really liked how it opened the logs in a separate tab. I've gone ahead and mimicked that functionality here meaning that toggle_logs(direction) becomes toggle_logs(). For the moment direction still exists, but only for the purpose to yell at you and tell you to remove it. So nothing will actually break if you're using this, just your direction will be ignored since now it will open in a new tab.

You can see the changes in #516.

[ckipp01]

Just a quick note that in 34569cc the deprecated direction is now removed.

[ckipp01]

In #552 there are a couple small changes to the Lua API to making the meaning of certain commands clearer.

• restart_server is renamed to restart_metals
• restart_build is renamed to restart_build_server

[ckipp01]

Just a heads up that it will now be required for users to be on at least 0.9.x of Neovim as I'm staring to use some of the new APIs that were released. For those of you that may be stuck for whatever reason you can target the v0.8.x tag, just know that there will be no more ongoing work there.