docs: ensure that lazy.nvim stays on latest `stable` tag

[firephreek]

Did you check docs and existing issues?

• I have read all the lazy.nvim docs
• I have updated the plugin to the latest version before submitting this issue
• I have searched the existing issues of lazy.nvim
• I have searched the existing issues of plugins related to this issue

Neovim version (nvim -v)

NVIM v0.11.4

Operating system/version

Debian

Describe the bug

After installing lazy.vim from the latest version/commit of the stable branch, it immediately reports back that updates are available. If a user updates, lazy.vim is taken off of the stable build and put into a 'nightly' build.

Steps To Reproduce

1. Follow the 'structured setup' installation, using the provided lazy.lua configuration.
   1a. Create an empty spec in the plugins directory. (lazy.vim breaks without this and it's not documented)
2. Launch Neovim
3. Run :Lazy to see the lazy.nvim menu.

Expected Behavior

I should see no plugins installed and a report that lazy.nvim is up-to-date. Instead, it says that there is 1 plugin installed and that lazy.nvim has an update available. Upon closer inspection, it can be seen that the updates pertain to the latest commits from the main branch. If a user updates neovim, they'll effectively be moving from a stable build to a nightly build. This is not desired behavior and it's not clear from the lazy.vim menu that this is happening especially given that the lazy.lua file is explicitly checking out the stable branch.

Repro

vim.env.LAZY_STDPATH = ".repro"
load(vim.fn.system("curl -s https://raw.githubusercontent.com/folke/lazy.nvim/main/bootstrap.lua"))()

require("lazy.minit").repro({
  spec = {
    -- add any other plugins here
  },
})

[dpetka2001]

The default setting is to always pull from latest git commit. See here

lazy.nvim/lua/lazy/core/config.lua

Lines 15 to 16 in 306a055

	version = nil, -- always use the latest git commit
	-- version = "*", -- try installing the latest stable version for plugins that support semver

If you want, you can change that setting in your personal configuration. It's also mentioned in the docs what are the default settings for lazy.nvim.

[firephreek]

That seems exceptionally counter-intuitive. A stable branch implies that other branches, main in particular, are not 'stable which is how I think every managed/OSS project I've ever come across behaves. So if it's the case that updates put a user on nightly (unstable), what's the point of even having a versioned stable branch? Shouldn't the default init file be updated to reflect that so it always pulls the project from main branch? You could still tag the main branch with a version number if it means anything, but it doesn't really seem like it does.

There's also a difference between documenting a configuration vs explaining a configuration. Given that lazy.vim is not abiding by generally accepted practices, it would be helpful to call that out up front. It might also be worth mentioning here that in those same docs, the default configuration is version = nil but immediately above that is suggests to "leave version=false". I'll admit that I'm not a Lua guru, but I don't think nil and false are the same thing, even in Lua. So should I be manually updating the configuration to the recommendations of the comments every time I have to re-install or can I rely on the those defaults?

It really does seem like the best answer to this would be to update the config file to keep a user on stable if that's what the default init is pulling from. Maybe we can parametrize it and pull from a config if a user is keen on being on nightly?

[dpetka2001]

You either put opts.defaults.version = "*" in your personal configuration to get stable releases or leave the default value which will pull from main. Simple as that.

Everyone is free to do whatever they want in their personal configuration.

nil and false might not be the same type of value but are both considered falsy in Lua. The link in the docs mentions the defaults of lazy.nvim which a user should read and then decide if those defaults suit him or not and make necessary changes in his personal configuration.

[clason]

stable is just a name with zero implications (in general). @dpetka2001 is correct: you(!) need to make your(!) intentions explicit in the config, either by specifying versions/tags or a branch.

[firephreek]

I think that's an unfortunate way to approach this issue, but I'm just a user.

@clason stable branches in the software industry tend to denote a release or version of the application that is free from any unexpected issues. Code from a "stable" branch typically has been generally tested and evaluated to ensure that the application does not break in an unexpected manner. This differs from 'nightly' releases where code may be undergoing testing or review and may not generally be considered 'safe' or conflict free. If stable has zero implications for the lazy.vim team then there shouldn't be a need for fresh installations of lazy.vim to be based on a stable branch, since, per what is being suggested here, main is (always) safe to update to.

lazy.nvim/lua/lazy/init.lua

Lines 123 to 134 in 306a055

	function M.bootstrap()
	local lazypath = vim.fn.stdpath("data") .. "/lazy/lazy.nvim"
	if not (vim.uv or vim.loop).fs_stat(lazypath) then
	vim.fn.system({
	"git",
	"clone",
	"--filter=blob:none",
	"https://github.com/folke/lazy.nvim.git",
	"--branch=stable", -- latest stable release
	lazypath,
	})
	end

[clason]

The point is merely about the implicit assumption, which is unsafe. Hence the need to be explicit.

(Note that this is irrelevant for lazy.nvim itself, which doesn't have a stable branch. It has a stable tag, though, which you can specify in the specs for lazy itself. Lazy doesn't know anything about your bootstrap process, so it can't know what you specified there.)

[firephreek]

@clason It's not really an implicit assumption if the code explicitly says --branch=stable which it does right there on line 131. If you're saying that a branch labeled stable doesn't exist, well, that's even more confusing and misleading don't you think? Why is lazy.vim installing from a tag and then telling users to immediately update, putting them off of something that was explicitly communicated as 'stable' only to put them on something that, well, isn't?

[clason]

Because I just explained to you the difference between the (manual) bootstrapping and the (controlled) update mechanism.

What you are asking for is for extra, non-trivial, "automagic" to save you the effort of explicitly specifying the update policy for lazy.nvim itself (in contrast to every other plugin).

[firephreek]

@clason You did, but only because I filed a bug and we started a conversation. None of this was otherwise covered, explained, or communicated in the docs. As a new user, following the installation steps, I would be left with the impression that I was on a 'stable' build of lazy.nvim, which, I'm actually not and will instead be pushed to always be on the bleeding edge.

In terms of trivial fixes

--- a/lua/lazy/core/config.lua
+++ b/lua/lazy/core/config.lua
-    version = nil, -- always use the latest git commit
+    version = "*", -- always use the latest git commit

and

--- a/lua/lazy/init.lua
+++ b/lua/lazy/init.lua
-      "--branch=stable", -- latest stable release

both seem rather trivial with the former ensuring that users remain on "stable" builds of lazy.vim (if there is such a thing I guess?) and the later ensuring that users are on the bleeding edge version, which seems to be the intent of the project.

[clason]

No, the former would change the default for everybody and every plugin. I don't think that's wanted.

You are correct that there is explicit information missing in the (reworked) documentation explaining how to pin lazy itself. (It's implicit in the plugin spec documentation since lazy is just a plugin, but that's obviously not enough.)