MAINTAINING.md
This document contains knowledge about specifically maintaining 'mini.nvim'. It assumes general knowledge about how Open Source and GitHub issues/PRs work.
See CONTRIBUTING.md for how to generate help files, run tests, and format.
setup(), and config.H helper table at the beginning to allow having exported code written before helpers (severely improves readability).setup() function with its helper functions: H.setup_config(), H.apply_config(), H.create_autocommands(), H.create_default_hl(), H.create_user_commands().H.get_config() and H.is_disabled() helpers. They both should respect buffer local configuration.ignore_text / ignore_attr behind narrowest Neovim version check), but testing some parts only on Nightly is allowed if needed (regenerate screenshot on Nightly and verify it only on versions starting from it).:helpand on nvim-mini.org site. In particular:
Prefer using # Section ~ and ## Subsection ~ explicit sections. This allows more structured table of contents and adds anchors for all of them.
Prefer using "naturally sounding" help tags for an entire section because they are transformed into a title. So like ---@tag MiniAi-builtin-textobjects and not ---@tag MiniAi-textobjects-builtin.
Do not use explicit right aligned tags, as they result into a separate high level heading on the site. This usually breaks hierarchical structure of the page (like if added as part of a MiniXxx.config section, it ends the config section and starts its own). Prefer to "naturally" incorporate a tag into a text in first line of its info or add it directly below a dedicated section. Examples:
--- # Important topic ~
--- *MiniXxx-important-topic*
---
--- A text about important topic of 'mini.xxx' module.
---
--- # Another topic ~
---
--- *MiniXxx-another-topic* is also important.
---
--- *MiniXxx-last-resort*
--- As last resort just add left aligned tag before first line
--- or at line start.
Mandatory:
nvim executable for latest stable release.git.StyLua with version described in CONTRIBUTING.md.make.Recommended:
nvim_07, nvim_08, nvim_09, nvim_010. This is useful for running tests on multiple versions.lua-language-server.pre-commit and enable it with pre-commit install and pre-commit install --hook-type commit-msg (run from repository's root).'<Cmd>lua MiniDoc.generate()<CR>' - to generate documentation.'<Cmd>lua MiniTest.run_at_location()<CR>' - to run test under cursor.'<Cmd>lua MiniTest.run_file()<CR>' - to run current test file.Aim for supporting 4 latest minor Neovim releases: current stable, current Nightly, and two latest stable releases.
For example, if 0.9.x is current stable, then all latest patch versions of 0.7, 0.8, 0.9 should be supported plus Nightly (0.10.0).
NOTE: some modules can have less supported versions during their release only if it is absolutely necessary for the core functionality.
Modules of 'mini.nvim' are distributed both as part of 'mini.nvim' repository and each one in its standalone repository. All development takes place in 'mini.nvim' while being synced to standalone ones. This is done by having special sync branch which points to the latest commit which was synced to standalone repositories.
Usual workflow involves performing these steps after every commit in 'mini.nvim':
Check out to main branch.
Ensure there are no immediate defects. Usually it means to wait until all CI checks passed.
Run make dual_sync. This should:
See 'scripts/dual_sync.sh' for more details.
Run make dual_log to make sure that all and correct patches were applied. If some commit touches files from several modules, it results into commits for every affected standalone repository.
Run make dual_push. This should:
sync branch to point to latest commit and push it to origin.main branch. Push main.make dual_sync to sync.make dual_log and look at changes which are about to be applied to standalone repositories. Make sure that they are what you'd expect.make dual_push to push changes to standalone repositories.Resolve #xxx at the bottom of commit message.Begin the process of stopping official support for outdated Neovim version shortly after (week or two) the release of the new stable one. Usually it is stopping support for Neovim 0.x (say, 0.8) shortly after the release of 0.(x+3).0 (say, 0.11.0). The deprecation should be done in two stages:
Stage 1, soft deprecation (to notify old version users about upcoming support drop):
setup() function body in every module:-- TODO: Remove after Neovim=0.8 support is dropped
if vim.fn.has('nvim-0.9') == 0 then
vim.notify(
'(mini.ai) Neovim<0.9 is soft deprecated (module works but not supported).'
.. ' It will be deprecated after next "mini.nvim" release (module might not work).'
.. ' Please update your Neovim version.'
)
end
Stage 2, deprecation:
vim.fn.has('nvim-0.x') and vim.fn.exists('+option') (if the option is present in all currently supported Neovim versions).Neovim{<,<=,=,>=,>}{0.x,0.(x+1)} (like Neovim<0.x, Neovim>=0.(x+1), etc.).As Neovim is in active development, from time to time there will be test failures only on Neovim Nightly (and not on earlier versions). Adjusting tests to pass on all supported versions is important. The sooner the better, as it will allow for an easier deduction of what Neovim change is responsible here.
For examples of how this was done in the past, search git log --oneline output for "Nightly". This is probably the best way to learn about different approaches.
Here is a rough outline of how to act (with some Git commit hashes for illustration):
Investigate if the change actually affects plugin functionality or is it only due to how the test is set up. Trying to manually reproduce the tested behavior on Nightly version is usually helpful for this decision.
Common examples of code related changes on Nightly:
848c5e8f428faf843051768e0d56104cd02aea1f.0f85c464605cab5ba922644d3f2508c6d62f258e.However, usually it is about how a test is set up. Some common examples:
bac6c8bb77fe0a872719ea43c39e35c7c695f05e) or the number of picker items in 'mini.pick' has changed (like in b409fd1d8b9ea7ec7c0923eb2562b52ed5d1ab0a)0a8a1072137d916406507c941698a4bfa9dbbe7a.c889667a9d73b106bd303a043eb37a91da4a41a2.If the change affects the code:
If the change only affects the test:
First try to adjust the test to pass on all supported Neovim versions. Like adding different code paths for Neovim>=0.xx and Neovim<0.xx.
This is usually not the case for failing screenshot testing. If feasible and can be done concisely, replace failing screenshot testing with other means of equivalent testing. Like in 68955a915c45ae7c988c539abe6e89f0971a9a2d.
If the previous path is not possible or is significantly complex, make an educated decision of whether test fail is related to the actually tested functionality or not.
If it tests something crucial, make the best effort to test on the widest forward-compatible set of Neovim versions. I.e. it should test on Neovim>=0.yy and not Neovim<=0.yy.
Usually it is good enough for non-crucial part of the test to make only a forward-compatible test that starts on current Nightly (as long as that version is being tested in CI).
Like in 3f5d06a6f710966cb93baaadc4897eeb6d6210e5 or be6979dddb339c4a548d2f1dac5c290b5bf73306.
Make adjustments and commit. Use commit message with title that contains "Nightly" and (preferably) with body describing the culprit for the change. This helps when searching the Git history for similar cases.
Mini*.config definition.H.setup_config() with type check of new setting.- FEATURE: Implement ....stable branch, as it won't work during beta-testing.make sync.quarto preview.main. Push main and sync dual distribution.make sync on main branch.There is no clear guidelines for when a stable (minor) release should be made. Mostly "when if feels right" but "not too often". If it has to be put in words, it is something like "After 3 new modules have finished beta-testing or 4 months, whichever is sooner". No patch releases have been made yet.
TODOs about actions to be done before release.release-0.xx branch.stable branch. Commit.release-0.xx to main and push it. Check that CI has passed.git tag -a v0.xx.0 -m 'Version 0.xx.0'. Push it.stable branch to point at new tag (git branch --force stable when on latest tag's commit). Push it.# REPLACE `xx` with your version number
TAG_NAME="v0.xx.0" TAG_MESSAGE="Version 0.xx.0" make dual_release
stable): manually visit some of them (at least new modules) on GitHub.TODOs about actions to be done after release.