From dd4cb94a0eb99f82012e3b4234c763897ccdfeb5 Mon Sep 17 00:00:00 2001 From: zuqini Date: Wed, 15 Apr 2026 10:06:49 +0000 Subject: [PATCH] docs: split general tips from lazy.nvim migration notes The install/update feedback bullet applies to every zpack user, not just migrators, so relocate it to a new "Tips" section. The passive libraries note stays under migration since it's framed against lazy.nvim's community-spec behavior. Also cross-link the noice.nvim compatibility note from the tips section, and mirror all of this in doc/zpack.txt (which missed the original tips additions). --- doc/zpack.txt | 31 +++++++++++++++++++++++++++++-- docs/tips.md | 8 ++++++-- 2 files changed, 35 insertions(+), 4 deletions(-) diff --git a/doc/zpack.txt b/doc/zpack.txt index 52b562d..241ba7d 100644 --- a/doc/zpack.txt +++ b/doc/zpack.txt @@ -870,8 +870,35 @@ dev mode Use `src = vim.fn.expand('~/projects/my_plugin.nvim')` profiling Use `nvim --startuptime startuptime.log`. Also see: https://gist.github.com/zuqini/35993710f81983fbfa6baca67bdb32ed + *zpack-migration-default-lazy* +default lazy plugins lazy.nvim's community specs silently default + top-level specs for utility libraries like + `plenary.nvim` to `lazy = true`, even without + lazy triggers or a lazy parent. zpack respects + your specs as-written, so set `lazy = true` + explicitly on such specs if you want the same + default. + +------------------------------------------------------------------------------ +11.2 TIPS *zpack-tips* + +General tips and gotchas when using zpack: + + *zpack-tip-install-update* +install/update feedback `vim.pack` surfaces install/update progress + via `:messages` (e.g. "vim.pack: Downloading + updates (0/83)"). These messages are hidden + if you have `vim.opt.cmdheight = 0`. Raise + it, check `:messages`, or route them through + a notifier: + - https://github.com/folke/snacks.nvim + - https://github.com/rcarriga/nvim-notify + - https://github.com/folke/noice.nvim + Also see |zpack-tip-noice| for compatibility + notes. + ------------------------------------------------------------------------------ -11.2 SNACKS.NVIM DASHBOARD *zpack-tip-snacks* +11.3 SNACKS.NVIM DASHBOARD *zpack-tip-snacks* The default Snacks.nvim dashboard configuration includes a startup time section that has a hard dependency on lazy.nvim. This will cause errors with @@ -892,7 +919,7 @@ To work around this, remove the startup section from your dashboard config: See: https://github.com/folke/snacks.nvim/issues/1778 ------------------------------------------------------------------------------ -11.3 NOICE.NVIM WITH VIM.PACK *zpack-tip-noice* +11.4 NOICE.NVIM WITH VIM.PACK *zpack-tip-noice* noice.nvim filters out `vim.pack` messages by default, which means you won't see install/update notifications from your plugin manager. diff --git a/docs/tips.md b/docs/tips.md index 22ed94e..59fec26 100644 --- a/docs/tips.md +++ b/docs/tips.md @@ -6,8 +6,12 @@ Most of your lazy.nvim plugin specs will work as-is with zpack. However, zpack f - **version pinning**: lazy.nvim's `version` field maps to zpack's `sem_version`. See [Spec Reference](spec.md) and [version pinning examples](examples.md#version-pinning-for-lazynvim-compatibility) - **dev mode**: Use `src = vim.fn.expand('~/projects/my_plugin.nvim')` for local development - **profiling**: Use `nvim --startuptime startuptime.log`. Also refer to example [Neovim Profiler script](https://gist.github.com/zuqini/35993710f81983fbfa6baca67bdb32ed) -- **install/update feedback**: `vim.pack` surfaces progress via `:messages` (e.g. `vim.pack: Downloading updates (0/83)`) instead of a dedicated UI. These messages are hidden if you have `vim.opt.cmdheight = 0` — raise it, check `:messages`, or route them through a notifier like [snacks.notifier](https://github.com/folke/snacks.nvim), [nvim-notify](https://github.com/rcarriga/nvim-notify), or [noice.nvim](https://github.com/folke/noice.nvim) -- **passive libraries**: lazy.nvim's community specs silently force utility libraries like `plenary.nvim` to `lazy = true` regardless of your config. zpack respects your spec as-written, so set `lazy = true` explicitly on pure-dependency plugins you don't want eager-loaded +- **default lazy plugins**: lazy.nvim's community specs silently default top-level specs for utility libraries like `plenary.nvim` to `lazy = true`, even without lazy triggers or a lazy parent. zpack respects your specs as-written, so set `lazy = true` explicitly on such specs if you want the same default + +## Tips + +General tips and gotchas when using zpack: +- **install/update feedback**: `vim.pack` surfaces install/update progress via `:messages` (e.g. `vim.pack: Downloading updates (0/83)`). These messages are hidden if you have `vim.opt.cmdheight = 0` — raise it, check `:messages`, or route them through a notifier like [snacks.notifier](https://github.com/folke/snacks.nvim), [nvim-notify](https://github.com/rcarriga/nvim-notify), or [noice.nvim](https://github.com/folke/noice.nvim). Also see [noice.nvim with vim.pack](#noicenvim-with-vimpack) for compatibility notes ## Compatibility Notes