mirror of
https://github.com/neovim/neovim.git
synced 2024-12-23 12:45:17 -07:00
docs: move vim-patch wiki page to runtime documentation
This commit is contained in:
dundargoc
Christian Clason
parent
fbd0f6658f
commit
7908dc0d15
@ -327,7 +327,7 @@ 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
|
||||
|
||||
304
runtime/doc/dev_vimpatch.txt
Normal file
304
runtime/doc/dev_vimpatch.txt
Normal file
@ -0,0 +1,304 @@
|
||||
*dev_vimpatch.txt* Nvim
|
||||
|
||||
NVIM REFERENCE MANUAL
|
||||
|
||||
Merging patches from Vim *dev-vimpatch*
|
||||
|
||||
|
||||
Nvim was forked from Vim 7.4.160; it is kept up-to-date with relevant Vim
|
||||
patches in order to avoid duplicate work. Run `vim-patch.sh`
|
||||
https://github.com/neovim/neovim/blob/master/scripts/vim-patch.sh to see the
|
||||
status of Vim patches:
|
||||
>bash
|
||||
./scripts/vim-patch.sh -l
|
||||
<
|
||||
Everyone is welcome to |dev-vimpatch-pull-requests| for relevant Vim
|
||||
patches, but some types of patches are |dev-vimpatch-not-applicable|.
|
||||
See |dev-vimpatch-quickstart| to get started immediately.
|
||||
|
||||
|
||||
Type |gO| to see the table of contents.
|
||||
|
||||
==============================================================================
|
||||
QUICKSTART *dev-vimpatch-quickstart*
|
||||
|
||||
1. Pull the Nvim source:
|
||||
>bash
|
||||
git clone https://github.com/neovim/neovim.git
|
||||
<
|
||||
2. Run `./scripts/vim-patch.sh -l` to see the list of missing Vim patches.
|
||||
|
||||
3. Choose a patch from the list (usually the oldest one), e.g. `8.0.0123`.
|
||||
|
||||
- Check for open vim-patch PRs
|
||||
https://github.com/neovim/neovim/pulls?q=is%3Apr+is%3Aopen+label%3Avim-patch.
|
||||
|
||||
4. Run `./scripts/vim-patch.sh -p 8.0.0123`
|
||||
|
||||
5. Follow the instructions given by the script.
|
||||
|
||||
NOTES ~
|
||||
|
||||
- It's strongly recommended to work on the oldest missing patch, because
|
||||
later patches might depend on the changes.
|
||||
- Use `git log --grep` or `git log -G` to search the Nvim/Vim source history
|
||||
(even deleted code). E.g. to find `reset_option_was_set`: >bash
|
||||
|
||||
git log -p -G reset_option_was_set
|
||||
<
|
||||
- Pass `git log` options like `--grep` and `-G` to `./scripts/vim-patch.sh -L`
|
||||
to filter unmerged Vim patches E.g. to find `+quickfix` patches: >bash
|
||||
|
||||
./scripts/vim-patch.sh -L --grep quickfix -- src
|
||||
<
|
||||
==============================================================================
|
||||
PULL REQUESTS *dev-vimpatch-pull-requests*
|
||||
|
||||
Note: vim-patch.sh automates these steps for you. Use it!
|
||||
|
||||
- Install `gh` (https://cli.github.com/) if you want to use `vim-patch.sh` to
|
||||
create PRs automatically
|
||||
- The pull request title should include `vim-patch:8.x.xxxx` (no whitespace)
|
||||
- The commit message
|
||||
https://github.com/neovim/neovim/commit/4ccf1125ff569eccfc34abc4ad794044c5ab7455
|
||||
should include:
|
||||
- A token indicating the Vim patch number, formatted as follows:
|
||||
`vim-patch:8.0.0123` (no whitespace)
|
||||
- A URL pointing to the Vim commit:
|
||||
https://github.com/vim/vim/commit/c8020ee825b9d9196b1329c0e097424576fc9b3a
|
||||
- The original Vim commit message, including author
|
||||
|
||||
Reviewers: hint for reviewing `runtime/` patches
|
||||
https://github.com/neovim/neovim/pull/1744#issuecomment-68202876
|
||||
|
||||
==============================================================================
|
||||
NA (NOT APPLICABLE) PATCHES *dev-vimpatch-not-applicable*
|
||||
|
||||
Many Vim patches are not applicable to Nvim. If you find NA patches, visit an
|
||||
open "version.c: update" pull request
|
||||
https://github.com/neovim/neovim/pulls?q=is%3Apr+author%3Aapp%2Fgithub-actions+version.c+is%3Aopen
|
||||
and mention the NA patches in a comment (please edit/update one comment,
|
||||
rather than adding a new comment for each patch).
|
||||
|
||||
If there are no open `version.c: update` pull requests, include NA patches in
|
||||
a commit message in the following format:
|
||||
>
|
||||
vim-patch:<version-or-commit>
|
||||
vim-patch:<version-or-commit>
|
||||
...
|
||||
<
|
||||
where `<version-or-commit>` is a valid Vim version (like `8.0.0123`) or
|
||||
commit-id (SHA). Each patch is on a separate line.
|
||||
|
||||
It is preferred to include NA patches by squashing it in applicable Vim
|
||||
patches, especially if the Vim patches are related. First line of the commit
|
||||
message should be from the applicable Vim patch.
|
||||
>
|
||||
./scripts/vim-patch -p <na-patch>
|
||||
./scripts/vim-patch -p <na-patch>
|
||||
...
|
||||
./scripts/vim-patch -P <patch>
|
||||
git rebase -i master
|
||||
<
|
||||
Example:
|
||||
https://github.com/neovim/neovim/commit/00f60c2ce78fc1280e93d5a36bc7b2267d5f4ac6
|
||||
|
||||
TYPES OF "NOT APPLICABLE" VIM PATCHES ~
|
||||
|
||||
- Vim9script features, and anything related to `:scriptversion`. (Nvim
|
||||
supports Vimscript version 1 only.) Be aware that patches labelled `Vim9:`
|
||||
may still contain applicable fixes to other parts of the codebase, so these
|
||||
patch need to be checked individually.
|
||||
- Updates to `testdir/Makefile` are usually NA because the Makefile implicitly
|
||||
finds
|
||||
https://github.com/neovim/neovim/commit/8a677f8a4bff6005fa39f090c14e970c3dfdbe6e#diff-b3c6ad6680a25a1b42095879e3a87104R52
|
||||
all `test_*.vim` files.
|
||||
- Compiler warning fixes: Nvim strives to have no warnings at all, and has a
|
||||
very different build system from Vim.
|
||||
- Note: Coverity fixes in Vim are relevant to Nvim.
|
||||
- `*.proto` changes: Nvim autogenerates function prototypes
|
||||
- `#ifdef` tweaking: For example, Vim decided to enable `FEAT_VISUAL` for all
|
||||
platforms - but Nvim already does that. Adding new `FEAT_` guards also isn't
|
||||
relevant to Nvim.
|
||||
- Legacy system support: Fixes for legacy systems such as Amiga, OS/2 Xenix,
|
||||
Mac OS 9, Windows older than XP SP2, are not needed because they are not
|
||||
supported by Nvim.
|
||||
- NA files: `src/Make_*`, `src/testdir/Make__*`
|
||||
- `if_*.c` changes: `if_python.c` et. al. were removed.
|
||||
- `term.c` changes: the Nvim TUI uses `libtermkey` to read terminal sequences;
|
||||
Vim's `term.c` was removed.
|
||||
- `job` patches: incompatible API and implementation
|
||||
- NA files: `src/channel_*`, `src/job_*`, `src/testdir/test_channel_*`,
|
||||
`src/testdir/test_job_*`
|
||||
- `:terminal` patches that modify NA files: incompatible API and
|
||||
implementation
|
||||
- NA files: `src/terminal_*`, `src/testdir/test_terminal_*`
|
||||
- `defaults.vim` patches
|
||||
- Most GUI-related changes: Nvim GUIs are implemented external to the core C
|
||||
codebase.
|
||||
- NA files: `src/gui_*`, `src/gvim_*`, `src/GvimExt/*`, `src/testdir/test_gui*`
|
||||
- `balloon` changes: Nvim does not support balloon feature
|
||||
- NA files: `src/beval_*`, `src/testdir/test_balloon_*`
|
||||
- libvterm changes: Nvim does not vendor libvterm in `src/`.
|
||||
- Screendump tests from `test_popupwin.vim`, `test_popupwin_textprop.vim`:
|
||||
https://github.com/neovim/neovim/pull/12741#issuecomment-704677141
|
||||
- json changes: incompatible API https://github.com/neovim/neovim/pull/4131
|
||||
- NA files: `src/json*`, `src/testdir/test_json.vim`
|
||||
- `test_restricted.vim` restricted mode is removed in
|
||||
https://github.com/neovim/neovim/pull/11996
|
||||
- Many tests in `test_prompt_buffer.vim` require incompatible Vim features
|
||||
such as `channel`; they should still be included, but skipped
|
||||
- non-runtime documentation: Moved to https://neovim.io/doc/,
|
||||
https://github.com/neovim/neovim/wiki#developers
|
||||
- NA files: `Filelist`, `README`, `INSTALL`,
|
||||
- Anything else might be relevant; err on the side of caution, and post an
|
||||
issue if you aren't sure.
|
||||
|
||||
==============================================================================
|
||||
VERSION.C *dev-vimpatch-version.c*
|
||||
|
||||
The list of Vim patches in `src/nvim/version.c` is automatically updated
|
||||
https://github.com/neovim/neovim/pull/7780 based on the presence of
|
||||
`vim-patch:xxx` tokens in the Nvim git log.
|
||||
|
||||
- Don't update `src/nvim/version.c` yourself.
|
||||
- `scripts/vim-patch.sh -p` intentionally omits `version.c` to avoid merge
|
||||
conflicts and save time when porting a patch.
|
||||
- The automation script (`scripts/vimpatch.lua`) only recognizes tokens like
|
||||
`vim-patch:8.0.1206`, not `vim-patch:<hash>`.
|
||||
|
||||
==============================================================================
|
||||
CODE DIFFERENCES *dev-vimpatch-code-differences*
|
||||
|
||||
The following functions have been removed or deprecated in favor of newer
|
||||
alternatives. See `memory.c`
|
||||
https://github.com/neovim/neovim/blob/master/src/nvim/memory.c for more
|
||||
information.
|
||||
>
|
||||
-----------------------------------------------------------------------
|
||||
Deprecated or removed Replacement
|
||||
-----------------------------------------------------------------------
|
||||
vim_free xfree
|
||||
VIM_CLEAR(&foo) XFREE_CLEAR(foo)
|
||||
malloc alloc lalloc lalloc_id ALLOC_ONE xmalloc
|
||||
calloc lalloc_clear xcalloc
|
||||
realloc vim_realloc xrealloc
|
||||
mch_memmove memmove
|
||||
vim_memset copy_chars copy_spaces memset
|
||||
vim_strbyte strchr
|
||||
vim_strncpy strncpy xstrlcpy
|
||||
vim_strcat strncat xstrlcat
|
||||
VIM_ISWHITE ascii_iswhite
|
||||
IS_WHITE_OR_NUL ascii_iswhite_or_nul
|
||||
vim_isalpha mb_isalpha
|
||||
vim_isNormalIDc ascii_isident
|
||||
vim_islower vim_isupper mb_islower mb_isupper
|
||||
vim_tolower vim_toupper mb_tolower mb_toupper
|
||||
mb_ptr2len utfc_ptr2len
|
||||
mb_ptr2len_len utfc_ptr2len_len
|
||||
mb_char2len utf_char2len
|
||||
mb_char2bytes utf_char2bytes
|
||||
mb_ptr2cells utf_ptr2cells
|
||||
mb_ptr2cells_len utf_ptr2cells_len
|
||||
mb_char2cells utf_char2cells
|
||||
mb_off2cells utf_off2cells
|
||||
mb_ptr2char utf_ptr2char
|
||||
mb_head_off utf_head_off
|
||||
mb_tail_off utf_cp_tail_off
|
||||
mb_lefthalve grid_lefthalve
|
||||
mb_fix_col grid_fix_col
|
||||
utf_off2cells grid_off2cells
|
||||
ml_get_curline get_cursor_line_ptr
|
||||
ml_get_cursor get_cursor_pos_ptr
|
||||
screen_char ui_line
|
||||
screen_line grid_put_linebuf
|
||||
screen_* (most functions) grid_*
|
||||
update_prepare, update_finish #9484 removed; use update_screen only
|
||||
ARRAY_LENGTH ARRAY_SIZE
|
||||
vim_strsave_escape_csi vim_strsave_escape_ks
|
||||
vim_unescape_csi vim_unescape_ks
|
||||
gettail path_tail
|
||||
mch_isFullName path_is_absolute
|
||||
script_do_profile profile_init
|
||||
|
||||
-----------------------------------------------------------------------
|
||||
<
|
||||
Make sure to note the difference between `utf_` and `utfc_` when replacing
|
||||
`mb_` functions. Also indirect call syntax `(*mb_ptr2len)(...)` should be
|
||||
replaced with an ordinary function call `utfc_ptr2len(...)`.
|
||||
>
|
||||
-----------------------------------------------------------------------
|
||||
Data type Format (Vim source) Portable format (Nvim source)
|
||||
------------ ----------------------- ----------------------------------
|
||||
long long "%lld" "%" PRId64
|
||||
size_t "%ld" "%zu"
|
||||
linenr_T "%ld" "%" PRIdLINENR
|
||||
-----------------------------------------------------------------------
|
||||
<
|
||||
- See also: https://github.com/neovim/neovim/pull/1729#discussion_r22423779
|
||||
- Vim's `ga_init2` was renamed to `ga_init` and the original `ga_init` is
|
||||
gone.
|
||||
- "Old style" Vim tests (`src/testdir/*.in`) should be converted to Lua tests
|
||||
(see #1286 https://github.com/neovim/neovim/issues/1286 and #1328
|
||||
https://github.com/neovim/neovim/pull/1328). See Checklist for migrating
|
||||
legacy tests
|
||||
https://github.com/neovim/neovim/blob/master/test/README.md#checklist-for-migrating-legacy-tests.
|
||||
- However, please do not convert "new style" Vim tests
|
||||
(`src/testdir/*.vim`) to Lua. The "new style" Vim tests are faster than
|
||||
the old ones, and converting them takes time and effort better spent
|
||||
elsewhere. Just copy them to `test/old/testdir/*.vim`.
|
||||
- Conditions that check `enc_utf8` or `has_mbyte` are obsolete (only the
|
||||
"true" case is applicable).
|
||||
- `enc_utf8` and `has_mbyte` macros were removed in
|
||||
https://github.com/neovim/neovim/pull/13293
|
||||
- Check for `CSI` in typeahead buffer is only necessary in Vim with
|
||||
`FEAT_GUI`. `CSI` does not have a special meaning in typeahead buffer in
|
||||
Nvim. (also see https://github.com/neovim/neovim/pull/16936)
|
||||
|
||||
==============================================================================
|
||||
LIST MANAGEMENT *dev-vimpatch-list-management*
|
||||
|
||||
Management of lists (types `list_T` and `listitem_T` from vim) was changed in
|
||||
https://github.com/neovim/neovim/pull/7708/. There is a lint against the "old"
|
||||
usage, but here are the most important changes.
|
||||
|
||||
Declarations for the table
|
||||
|
||||
- `list_T list`: a list
|
||||
- `listitem_T li`: an item of `list`
|
||||
- `int val` a value for `lv_copyID`
|
||||
|
||||
>
|
||||
--------------------------------------------------------------------------------------
|
||||
Old New Comment
|
||||
------------------------------- ------------------------------------------------------
|
||||
list->lv_first tv_list_first(list)
|
||||
list->lv_last tv_list_last(list)
|
||||
li->li_next TV_LIST_ITEM_NEXT(list, li) To be avoided if possible, must use list which li belongs to.
|
||||
li->li_prev TV_LIST_ITEM_PREV(list, li) To be avoided if possible, must use list which li belongs to.
|
||||
Suggestion by @ZyX-l: Use TV_LIST_ITER or indexing instead of the previous two calls.
|
||||
list->lv_len tv_list_len(list)
|
||||
list->lv_lock tv_list_locked(list)
|
||||
&li->li_tv TV_LIST_ITEM_TV(li)
|
||||
list->lv_refcount++ tv_list_ref(list)
|
||||
val = list->lv_copyID val = tv_list_copyid(list)
|
||||
list->lv_copyID = val tv_list_set_copyid(list, val)
|
||||
|
||||
for (li = list->lv_first; TV_LIST_ITER_CONST(list, li, Use TV_LIST_ITER(...) if you need to
|
||||
li != NULL && another_cond; { if (another_cond) {break;} code}) modify list items (note: assigning copyID is also modification and this happens
|
||||
li = li->li_next) code always when recursively traversing a list).
|
||||
|
||||
--------------------------------------------------------------------------------------
|
||||
<
|
||||
For more details and some more advanced usage, see `typval.h` and `typval.c`.
|
||||
|
||||
==============================================================================
|
||||
DOCUMENTATION DIFFERENCES *dev-vimpatch-documentation*
|
||||
|
||||
The following should be removed from all imported documentation, and not be
|
||||
used in new documentation:
|
||||
|
||||
- `{Only when compiled with ...}`: the vast majority of features have been
|
||||
made non-optional (see https://github.com/neovim/neovim/wiki/Introduction)
|
||||
|
||||
vim:tw=78:ts=8:noet:ft=help:norl:
|
||||
@ -170,6 +170,7 @@ DEVELOPING NVIM
|
||||
|dev-style| Development style guidelines
|
||||
|dev-theme| Design guidelines (colorschemes etc.)
|
||||
|dev-tools| Tools and techniques for developing Nvim
|
||||
|dev-vimpatch| Merging patches from Vim
|
||||
|
||||
Standard plugins ~
|
||||
*standard-plugin-list*
|
||||
|
||||
@ -24,7 +24,7 @@ CREATED_FILES=()
|
||||
|
||||
usage() {
|
||||
echo "Port Vim patches to Neovim"
|
||||
echo "https://github.com/neovim/neovim/wiki/Merging-patches-from-upstream-vim"
|
||||
echo "https://neovim.io/doc/user/dev_vimpatch.html"
|
||||
echo
|
||||
echo "Usage: ${BASENAME} [-h | -l | -p vim-revision | -r pr-number]"
|
||||
echo
|
||||
@ -427,7 +427,7 @@ stage_patch() {
|
||||
or "%s -s --draft" to create a draft pull request.
|
||||
|
||||
See the wiki for more information:
|
||||
* https://github.com/neovim/neovim/wiki/Merging-patches-from-upstream-vim
|
||||
* https://neovim.io/doc/user/dev_vimpatch.html
|
||||
' "${vim_version}" "${BASENAME}" "${BASENAME}" "${BASENAME}"
|
||||
return $ret
|
||||
}
|
||||
|
||||
Loading…
Reference in New Issue
Block a user