diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b157277519..8f0947acf7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,7 +3,7 @@ Patches are welcome in whatever form. Discussions about patches happen on the [vim-dev][0] mailing list. If you create a pull request on GitHub it will be -forwarded to the vim-dev mailing list. You can also send your patch there +forwarded to the vim-dev mailing list. You can also send your patch there directly (but please note, the initial posting is subject to moderation). In that case an attachment with a unified diff format is preferred. Information about the mailing list can be found [on the Vim website][0] @@ -12,14 +12,14 @@ A pull request has the advantage that it will trigger the Continuous Integration tests, you will be warned of problems (you can ignore the coverage warning, it's noisy). -Please consider adding a test. All new functionality should be tested and bug +Please consider adding a test. All new functionality should be tested and bug fixes should be tested for regressions: the test should fail before the fix and -pass after the fix. Look through recent patches for examples and find help -with ":help testing". The tests are located under "src/testdir". +pass after the fix. Look through recent patches for examples and find help +with ":help testing". The tests are located under "src/testdir". -Contributions will be distributed with Vim under the Vim license. Providing a +Contributions will be distributed with Vim under the Vim license. Providing a change to be included implies that you agree with this and your contribution -does not cause us trouble with trademarks or patents. There is no CLA to sign. +does not cause us trouble with trademarks or patents. There is no CLA to sign. ## Signing-off commits @@ -27,9 +27,9 @@ While not required, it's recommended to use **Signed-off commits** to ensure transparency, accountability, and compliance with open-source best practices. Signed-off commits follow the [Developer Certificate of Origin (DCO)][15], which confirms that contributors have the right to submit their changes under -the project's license. This process adds a `Signed-off-by` line to commit +the project's license. This process adds a `Signed-off-by` line to commit messages, verifying that the contributor agrees to the project's licensing -terms. To sign off a commit, simply use the -s flag when committing: +terms. To sign off a commit, simply use the -s flag when committing: ```sh git commit -s @@ -37,7 +37,7 @@ git commit -s This ensures that every contribution is properly documented and traceable, aligning with industry standards used in projects like the Linux Kernel or -the git project. By making Signed-off commits a standard practice, we help +the git project. By making Signed-off commits a standard practice, we help maintain a legally compliant and well-governed codebase while fostering trust within our contributor community. @@ -48,12 +48,12 @@ approvers are happy with that particular change. # Reporting issues -We use GitHub issues, but that is not a requirement. Writing to the Vim +We use GitHub issues, but that is not a requirement. Writing to the Vim mailing list is also fine. Please use the GitHub issues only for actual issues. If you are not 100% sure that your problem is a Vim issue, please first discuss this on the Vim user -mailing list. Try reproducing the problem without any of your plugins or settings: +mailing list. Try reproducing the problem without any of your plugins or settings: vim --clean @@ -77,7 +77,7 @@ or may not work with older Vim releases (since they may contain new features). If you find a problem with one of these files or have a suggestion for improvement, please first try to contact the maintainer directly. Look in the header of the file for the name, email address, github handle and/or -upstream repository. You may also check the [MAINTAINERS][11] file. +upstream repository. You may also check the [MAINTAINERS][11] file. The maintainer will take care of issues and send updates to the Vim project for distribution with Vim. @@ -88,23 +88,25 @@ If the maintainer does not respond, contact the [vim-dev][0] mailing list. If you want to contribute new runtime files for Vim or Neovim, please create a PR with your changes against this repository here. For new filetypes, do not forget: -* to add a new [filetype test][12] (keep it similar to the other filetype tests). -* all configuration switches should be documented + +- to add a new [filetype test][12] (keep it similar to the other filetype tests). +- all configuration switches should be documented (check [filetype.txt][13] and/or [syntax.txt][14] for filetype and syntax plugins) -* add yourself as Maintainer to the top of file (again, keep the header similar to +- add yourself as Maintainer to the top of file (again, keep the header similar to other runtime files) -* add yourself to the [MAINTAINERS][11] file. +- add yourself to the [MAINTAINERS][11] file. # Translations -Translating messages and runtime files is very much appreciated! These things +Translating messages and runtime files is very much appreciated! These things can be translated: -* Messages in Vim, see [src/po/README.txt][1] - Also used for the desktop icons. -* Menus, see [runtime/lang/README.txt][2] -* Vim tutor, see [runtime/tutor/README.txt][3] -* Manual pages, see [runtime/doc/\*.1][4] for examples -* Installer, see [nsis/lang/README.txt][5] + +- Messages in Vim, see [src/po/README.txt][1] + Also used for the desktop icons. +- Menus, see [runtime/lang/README.txt][2] +- Vim tutor, see [runtime/tutor/README.txt][3] +- Manual pages, see [runtime/doc/\*.1][4] for examples +- Installer, see [nsis/lang/README.txt][5] The help files can be translated and made available separately. See https://www.vim.org/translations.php for examples. @@ -113,9 +115,11 @@ See https://www.vim.org/translations.php for examples. Please have a look at the following [discussion][6], which should give you some ideas. Please also check the [develop.txt][7] helpfile for the recommended -style. Often it's also beneficial to check the surrounding code for the style +coding style. Often it's also beneficial to check the surrounding code for the style being used. +For the recommended documentation style, please check [helphelp.txt][16]. + # I have a question If you have some question on the style guide, please contact the [vim-dev][0] @@ -139,3 +143,4 @@ mailing list. For other questions please use the [Vi Stack Exchange][8] website, [13]: https://github.com/vim/vim/blob/master/runtime/doc/filetype.txt [14]: https://github.com/vim/vim/blob/master/runtime/doc/syntax.txt [15]: https://en.wikipedia.org/wiki/Developer_Certificate_of_Origin +[16]: https://github.com/vim/vim/blob/master/runtime/doc/helphelp.txt diff --git a/runtime/doc/helphelp.txt b/runtime/doc/helphelp.txt index c49a4d50b5..f3c5293b78 100644 --- a/runtime/doc/helphelp.txt +++ b/runtime/doc/helphelp.txt @@ -1,4 +1,4 @@ -*helphelp.txt* For Vim version 9.1. Last change: 2025 Jun 03 +*helphelp.txt* For Vim version 9.1. Last change: 2025 Jul 07 VIM REFERENCE MANUAL by Bram Moolenaar @@ -410,6 +410,24 @@ and 'tabstop' options and the 'filetype' to "help". Never set a global option in such a modeline, that can have undesired consequences. +STYLE + +If your Vim has 'modeline' enabled, Vim should follow the preferred style +automatically when editing built-in help files. + +Vim help files should be formatted for a 'textwidth' of 78 characters, so they +look good in a typical 80 x 24 terminal window. + +Use two spaces between the final dot of a sentence of the first letter of the +next sentence. Like this. + +Use tab characters for aligning content, with a 'tabstop' setting of 8. +This also helps reduce the file size. + +Always use |:retab| after you have finished editing. Don't blindly use +|:retab!|, always review what will be changed to avoid unwanted changes. + + TAGS To define a help tag, place the name between asterisks ("*tag-name*"). The