Thank you for your willingness to contribute to 'mini.nvim'. It means a lot!
You can make contributions in the following ways:
- Mention it somehow to help reach broader audience. This helps a lot.
- Create a GitHub issue. It can be one of the following types:
- Bug report. Describe your actions in a reproducible way along with their effect and what you expected should happen. Before making one, please make your best efforts to make sure that it is not an intended behavior (not described in documentation as such).
- Feature request. A concise and justified description of what one or several modules should be able to do. Before making one, please make your best efforts to make sure that it is not a feature that won't get implemented (these should be described in documentation; for example: block comments in 'mini.comment').
- Create a pull request (PR). It can be one of the following types:
- Code related. For example, fix a bug or implement a feature. Before even starting one, please make sure that it is aligned with project vision and goals. The best way to do so is to receive positive feedback from maintainer on your initiative in one of the GitHub issues (existing or created by you). Please, make sure to regenerate latest help file and that all tests pass (see later sections).
- Documentation related. For example, fix typo/wording in 'README.md', code comments or annotations (which are used to generate Neovim documentation; see later section). Feel free to make these without creating a GitHub issue.
- Add plugin integration to 'mini.base16' and 'mini.hues' modules.
- Add explicit support to other colorschemes. Every 'mini.nvim' module supports any colorscheme right out of the box. This is done by making most highlight groups be linked to a semantically similar builtin highlight group. Other groups are hard-coded based on personal preference. However, these choices might be out of tune with a particular colorscheme. Updating as many colorschemes as possible to have explicit 'mini.nvim' support is highly appreciated. For your convenience, there is a list of all highlight groups in later section of this file.
- Participate in discussions.
All well-intentioned, polite, and respectful contributions are always welcome! Thanks for reading this!
-
Try to make commit message as concise as possible while giving enough information about nature of a change. Think about whether it will be easy to understand in one year time when browsing through commit history.
-
Single commit should change either zero or one module, or affect all modules (i.e. enforcing some universal rule but not necessarily change files). Changes for two or more modules should be split in several module-specific commits.
-
Use Conventional commits style:
-
Messages should have the following structure:
<type>[optional scope][!]: <description> <empty line> [optional body] <empty line> [optional footer(s)]
-
<type>
is mandatory and can be one of:ci
- change in how automation (GitHub actions, dual distribution scripts, etc.) is done.docs
- change in user facing documentation (help, README, CONTRIBUTING, etc.).feat
- adding new user facing feature.fix
- resolving user facing issue.refactor
- change in code or documentation that should not affect users.style
- change in convention of how something should be done (formatting, wording, etc.) and its effects.test
- change in tests. For temporary commits which later should be squashed (when working on PR, for example), usefixup
type.
-
[optional scope]
, if present, should be done in parenthesis()
. If commit changes single module (as it usually should), using scope with module name is mandatory. If commit enforces something for all modules, useALL
scope. -
Breaking change, if present, should be expressed with
!
before:
. -
<description>
is a change overview in imperative, present tense ("change" not "changed" nor "changes"). Should result into first line under 72 characters. Should start with not capitalized word and NOT end with sentence ending punctuation (i.e. one of.,?!;
). -
[optional body]
, if present, should contain details and motivation about the change in plain language. Should be formatted to have maximum 80 characters in line. -
[optional footer(s)]
, if present, should be instruction(s) to Git or Github. Use "Resolve #xxx" on separate line if this commit resolves issue or PR.
-
-
Use module's function and field names without module's name. Like
add()
and notMiniSurround.add()
.
Examples:
feat(deps): add folds in update confirmation buffer
fix(jump): make operator not delete one character if target is not found
One main goal is to do that in a dot-repeatable way, because this is very
likely to be repeated after an unfortunate first try.
Resolve #688
refactor(bracketed): do not source 'vim.treesitter' on `require()`
Although less explicit, this considerably reduces startup footprint of
'mini.bracketed' in isolation.
feat(hues)!: update verbatim text to be distinctive
test(ALL): update screenshots to work on Nightly
- To lint messages of already done commits, execute
scripts/lintcommit-ci.sh <git-log-range>
. For example, to lint currently latest commit usescripts/lintcommit-ci.sh HEAD~..HEAD
. - To lint commit message before doing commit, install
pre-commit
and enable it withpre-commit install --hook-type commit-msg
(from the root directory). NOTE: requiresnvim
executable. If it throws (usually descriptive) error - recommit with proper message.
If your contribution updates annotations used to generate help file, please regenerate it. You can make this with one of the following (assuming current directory being project root):
- From command line execute
make documentation
. - Inside Neovim instance run
:luafile scripts/minidoc.lua
or:lua require('mini.doc').generate()
.
If your contribution updates code, please make sure that it doesn't break existing tests. If it adds new functionality or fixes a recognized bug, add new test case(s). There are two ways of running tests:
- From command line:
- Execute
make test
to run all tests (withnvim
as executable). - Execute
FILE=tests/test_xxx.lua make test_file
to run tests only from filetests/test_xxx.lua
(withnvim
as executable). - If you have multiple Neovim executables (say,
nvim_07
,nvim_08
,nvim_09
,nvim_010
), you can useNVIM_EXEC
variable to tests against multiple versions like this:NVIM_EXEC="nvim_07 nvim_08 nvim_09 nvim_010" make test
orNVIM_EXEC="nvim_07 nvim_08 nvim_09 nvim_010" FILE=tests/test_xxx.lua make test_file
.
- Execute
- Inside Neovim instance execute
:lua require('mini.test').setup(); MiniTest.run()
to run all tests or:lua require('mini.test').setup(); MiniTest.run_file()
to run tests only from current buffer.
This plugin uses 'mini.test' to manage its tests. For a more hands-on introduction, see TESTING.md.
Notes:
- If new functionality relies on an external dependency (
git
CLI tool, LSP server, etc.), use mocking (writing Lua code which emulates dependency usage as close as reasonably possible). For examples, take a look at tests for 'mini.pick', 'mini.completion', and 'mini.statusline'. - There is a certain number of tests that are flaky (i.e. will sometimes report an error due to other reasons than actual functionality being broke). It is usually the ones which test time related functionality (i.e. that certain action was done after specific amount of delay). A commonly used way to know if the test is flaky is that it fails on non-nightly Neovim version yet there were no changes to its tested module after it had passed in the past. For example, some 'mini.animate' test is shown to break but there were no changes to it since test passed in CI couple of days before. In case there is some test breaking which reasonably should not, rerun that test (or the whole file) at least several times.
- Advice for writing more robust tests:
- To test asynchronous or slow execution, use common
sleep()
test helper. For a more robust testing code, never directly use numbers to compute sleep time. Use precomputed time delay constants, which should always take into account different testing OSs (like be bigger on Windows, etc.). If module testing requires its extensive use and tests can not be made robust enough (examples are 'mini.animate', 'mini.jump', etc.), consider using it with argument that skips entire test case ifsleep()
is called in slow context. - Take into account that Windows uses "" as default path separator instead of Unix "/". This should be accounted either in module's code (preferably) or in test files (for example, by computing path separator and relying on it).
- To test asynchronous or slow execution, use common
This project uses StyLua version 0.19.0 for formatting Lua code. Before making changes to code, please:
- Install StyLua. NOTE: use
v0.19.0
. - Format with it. Currently there are two ways to do this:
- Manually run
stylua .
from the root directory of this project. - Install
pre-commit
and enable it withpre-commit install
(from the root directory). This will auto-format relevant code before making commits.
- Manually run
Here is a list of all highlight groups defined inside 'mini.nvim' modules. See documentation in 'doc' directory to find out what they are used for.
-
'mini.animate':
MiniAnimateCursor
MiniAnimateNormalFloat
-
'mini.clue':
MiniClueBorder
MiniClueDescGroup
MiniClueDescSingle
MiniClueNextKey
MiniClueNextKeyWithPostkeys
MiniClueSeparator
MiniClueTitle
-
'mini.completion':
MiniCompletionActiveParameter
-
'mini.cursorword':
MiniCursorword
MiniCursorwordCurrent
-
'mini.deps':
MiniDepsChangeAdded
MiniDepsChangeRemoved
MiniDepsHint
MiniDepsInfo
MiniDepsMsgBreaking
MiniDepsPlaceholder
MiniDepsTitle
MiniDepsTitleError
MiniDepsTitleSame
MiniDepsTitleUpdate
-
'mini.diff':
MiniDiffSignAdd
MiniDiffSignChange
MiniDiffSignDelete
MiniDiffOverAdd
MiniDiffOverChange
MiniDiffOverContext
MiniDiffOverDelete
-
'mini.files':
MiniFilesBorder
MiniFilesBorderModified
MiniFilesCursorLine
MiniFilesDirectory
MiniFilesFile
MiniFilesNormal
MiniFilesTitle
MiniFilesTitleFocused
-
'mini.hipatterns':
MiniHipatternsFixme
MiniHipatternsHack
MiniHipatternsNote
MiniHipatternsTodo
-
'mini.icons':
MiniIconsAzure
MiniIconsBlue
MiniIconsCyan
MiniIconsGreen
MiniIconsGrey
MiniIconsOrange
MiniIconsPurple
MiniIconsRed
MiniIconsYellow
-
'mini.indentscope':
MiniIndentscopeSymbol
MiniIndentscopeSymbolOff
-
'mini.jump':
MiniJump
-
'mini.jump2d':
MiniJump2dDim
MiniJump2dSpot
MiniJump2dSpotAhead
MiniJump2dSpotUnique
-
'mini.map':
MiniMapNormal
MiniMapSymbolCount
MiniMapSymbolLine
MiniMapSymbolView
-
'mini.notify':
MiniNotifyBorder
MiniNotifyNormal
MiniNotifyTitle
-
'mini.operators':
MiniOperatorsExchangeFrom
-
'mini.pick':
MiniPickBorder
MiniPickBorderBusy
MiniPickBorderText
MiniPickCursor
MiniPickIconDirectory
MiniPickIconFile
MiniPickHeader
MiniPickMatchCurrent
MiniPickMatchMarked
MiniPickMatchRanges
MiniPickNormal
MiniPickPreviewLine
MiniPickPreviewRegion
MiniPickPrompt
-
'mini.starter':
MiniStarterCurrent
MiniStarterFooter
MiniStarterHeader
MiniStarterInactive
MiniStarterItem
MiniStarterItemBullet
MiniStarterItemPrefix
MiniStarterSection
MiniStarterQuery
-
'mini.statusline':
MiniStatuslineDevinfo
MiniStatuslineFileinfo
MiniStatuslineFilename
MiniStatuslineInactive
MiniStatuslineModeCommand
MiniStatuslineModeInsert
MiniStatuslineModeNormal
MiniStatuslineModeOther
MiniStatuslineModeReplace
MiniStatuslineModeVisual
-
'mini.surround':
MiniSurround
-
'mini.tabline':
MiniTablineCurrent
MiniTablineFill
MiniTablineHidden
MiniTablineModifiedCurrent
MiniTablineModifiedHidden
MiniTablineModifiedVisible
MiniTablineTabpagesection
MiniTablineVisible
-
'mini.test':
MiniTestEmphasis
MiniTestFail
MiniTestPass
-
'mini.trailspace':
MiniTrailspace