diff options
Diffstat (limited to 'CONTRIBUTING.md')
| -rw-r--r-- | CONTRIBUTING.md | 44 |
1 files changed, 30 insertions, 14 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4f9c0d720d..2f5c2cce5a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -21,10 +21,11 @@ Reporting problems - [Search existing issues][github-issues] (including closed!) - Update Neovim to the latest version to see if your problem persists. - Try to reproduce with `nvim --clean` ("factory defaults"). +- If a specific configuration or plugin is necessary to recreate the problem, use the minimal template in `contrib/minimal.lua` with `nvim --clean -u contrib/minimal.lua` after making the necessary changes. - [Bisect](https://neovim.io/doc/user/starting.html#bisect) your config: disable plugins incrementally, to narrow down the cause of the issue. - [Bisect][git-bisect] Neovim's source code to find the cause of a regression, if you can. This is _extremely_ helpful. -- When reporting a crash, [include a stacktrace](https://github.com/neovim/neovim/wiki/FAQ#backtrace-linux). -- Use [ASAN/UBSAN](#clang-sanitizers-asan-and-ubsan) to get detailed errors for segfaults and undefined behavior. +- When reporting a crash, [include a stacktrace](https://neovim.io/doc/user/dev_tools.html#dev-tools-backtrace). +- Use [ASAN/UBSAN](#sanitizers-asan-and-ubsan) to get detailed errors for segfaults and undefined behavior. - Check the logs. `:edit $NVIM_LOG_FILE` - Include `cmake --system-information` for build-related issues. @@ -148,8 +149,10 @@ View the [Clang report] to see potential bugs found by the Clang ### Coverity -[Coverity](https://scan.coverity.com/projects/neovim-neovim) runs against the -master build. To view the defects, just request access; you will be approved. +Coverity runs against the master build. To view the defects you must +[request access](https://scan.coverity.com/projects/neovim-neovim) (Coverity +does not have a "public" view), then you will be approved as soon as +a maintainer sees the email. - Use this format for commit messages (where `{id}` is the CID (Coverity ID); ([example](https://github.com/neovim/neovim/pull/804))): @@ -262,12 +265,23 @@ Many `:help` docs are autogenerated from (C or Lua) docstrings. To generate the make doc ``` +To validate the documentation files, run: + +```bash +make lintdoc +``` + If you need to modify or debug the documentation flow, these are the main files: -- `./scripts/gen_vimdoc.py`: - Main doc generator. Drives doxygen to generate xml files, and scrapes those - xml files to render vimdoc files. -- `./scripts/lua2dox.lua`: - Used by `gen_vimdoc.py` to transform Lua files into a format compatible with doxygen. +- `./scripts/gen_vimdoc.lua`: + Main doc generator. Parses C and Lua files to render vimdoc files. +- `./scripts/luacats_parser.lua`: + Documentation parser for Lua files. +- `./scripts/cdoc_parser.lua`: + Documentation parser for C files. +- `./scripts/luacats_grammar.lua`: + Lpeg grammar for LuaCATS +- `./scripts/cdoc_grammar.lua`: + Lpeg grammar for C doc comments - `./scripts/gen_eval_files.lua`: Generates documentation and Lua type files from metadata files: ``` @@ -279,10 +293,12 @@ If you need to modify or debug the documentation flow, these are the main files: src/nvim/options.lua => runtime/doc/options.txt ``` +- `./scripts/lintdoc.lua`: Validation and linting of documentation files. + ### Lua docstrings Use [LuaLS] annotations in Lua docstrings to annotate parameter types, return -types, etc. See [:help dev-doc-lua][dev-doc-lua]. +types, etc. See [:help dev-lua-doc][dev-lua-doc]. - The template for function documentation is: ```lua @@ -326,12 +342,12 @@ as context, use the `-W` argument as well. [Clang report]: https://neovim.io/doc/reports/clang/ [GitHub Actions]: https://github.com/neovim/neovim/actions [clangd]: https://clangd.llvm.org -[Merge a Vim patch]: https://github.com/neovim/neovim/wiki/Merging-patches-from-upstream-Vim +[Merge a Vim patch]: https://neovim.io/doc/user/dev_vimpatch.html [complexity:low]: https://github.com/neovim/neovim/issues?q=is%3Aopen+is%3Aissue+label%3Acomplexity%3Alow [conventional_commits]: https://www.conventionalcommits.org [dev-doc-guide]: https://neovim.io/doc/user/develop.html#dev-doc -[dev-doc-lua]: https://neovim.io/doc/user/develop.html#dev-lua-doc -[LuaLS]: https://github.com/LuaLS/lua-language-server/wiki/Annotations +[dev-lua-doc]: https://neovim.io/doc/user/develop.html#dev-lua-doc +[LuaLS]: https://luals.github.io/wiki/annotations/ [gcc-warnings]: https://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html [gh]: https://cli.github.com/ [git-bisect]: http://git-scm.com/book/en/v2/Git-Tools-Debugging-with-Git @@ -346,4 +362,4 @@ as context, use the `-W` argument as well. [pr-ready]: https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request [run-tests]: https://github.com/neovim/neovim/blob/master/test/README.md#running-tests [style-guide]: https://neovim.io/doc/user/dev_style.html#dev-style -[wiki-faq]: https://github.com/neovim/neovim/wiki/FAQ +[wiki-faq]: https://neovim.io/doc/user/faq.html |