mirror of
https://github.com/neovim/neovim.git
synced 2024-09-17 20:58:20 -04:00
doc: api-contract, CONTRIBUTING.md
This commit is contained in:
Justin M. Keyes
parent
29ab8c1ae2
commit
6bc6d94ec8
@ -6,10 +6,15 @@ Getting started
|
||||
If you want to help but don't know where to start, here are some
|
||||
low-risk/isolated tasks:
|
||||
|
||||
- Help us [review pull requests](#reviewing)!
|
||||
- Merge a [Vim patch].
|
||||
- Try a [complexity:low] issue.
|
||||
- Fix [clang-scan] or [coverity](#coverity) warnings.
|
||||
- Fix [clang-scan], [coverity](#coverity), and [PVS](#pvs-studio) warnings.
|
||||
|
||||
Developer guidelines
|
||||
--------------------
|
||||
|
||||
- Nvim developers should read `:help dev-help`.
|
||||
- External UI developers should read `:help dev-ui`.
|
||||
|
||||
Reporting problems
|
||||
------------------
|
||||
@ -26,27 +31,25 @@ Reporting problems
|
||||
Pull requests ("PRs")
|
||||
---------------------
|
||||
|
||||
- To avoid duplicate work, you may want to create a `[WIP]` pull request so that
|
||||
others know what you are working on.
|
||||
- Avoid cosmetic changes to unrelated files in the same commit: extra noise
|
||||
makes reviews more difficult.
|
||||
- To avoid duplicate work, create a `[WIP]` pull request as soon as possible.
|
||||
- Avoid cosmetic changes to unrelated files in the same commit: noise makes
|
||||
reviews take longer.
|
||||
- Use a [feature branch][git-feature-branch] instead of the master branch.
|
||||
- Edit history with `ri` alias: add
|
||||
|
||||
[alias]
|
||||
ri = "!sh -c 't=\"${1:-master}\" ; s=\"${2:-HEAD}\" ; if git merge-base --is-ancestor \"$t\" \"$s\" ; then o=\"$t\" ; else mb=\"$(git merge-base \"$t\" \"$s\")\" ; if test \"x$mb\" = x ; then o=\"$t\" ; else lm=\"$(git log -n1 --merges \"$t..$s\" --pretty=%H)\" ; if test \"x$lm\" = x ; then o=\"$mb\" ; else o=\"$lm\" ; fi ; fi ; fi ; [ $# -gt 0 ] && shift ; [ $# -gt 0 ] && shift ; git rebase --interactive \"$o\" \"$@\"' -"
|
||||
|
||||
to your `~/.gitconfig`.
|
||||
|
||||
- Use a **rebase workflow** for small PRs.
|
||||
- After addressing review comments, it's fine to rebase and force-push.
|
||||
- Use a **merge workflow** for big, high-risk PRs.
|
||||
- Merge `master` into your PR when there are conflicts or when master
|
||||
introduces breaking changes.
|
||||
- Use the `ri` git alias:
|
||||
```
|
||||
[alias]
|
||||
ri = "!sh -c 't=\"${1:-master}\" ; s=\"${2:-HEAD}\" ; if git merge-base --is-ancestor \"$t\" \"$s\" ; then o=\"$t\" ; else mb=\"$(git merge-base \"$t\" \"$s\")\" ; if test \"x$mb\" = x ; then o=\"$t\" ; else lm=\"$(git log -n1 --merges \"$t..$s\" --pretty=%H)\" ; if test \"x$lm\" = x ; then o=\"$mb\" ; else o=\"$lm\" ; fi ; fi ; fi ; [ $# -gt 0 ] && shift ; [ $# -gt 0 ] && shift ; git rebase --interactive \"$o\" \"$@\"' -"
|
||||
```
|
||||
This avoids unnecessary rebases yet still allows you to combine related
|
||||
commits, separate monolithic commits, etc.
|
||||
- Rebase relatively small PRs, using `exec make -C build unittest` after
|
||||
each pick/edit/reword, after all following squash/fixup.
|
||||
- Merge in `master` of bigger PRs. Do not do excessive merging: merge
|
||||
in case of merge conflicts or when master introduces changes which break
|
||||
your PR.
|
||||
|
||||
Do not edit commits which come before the merge commit.
|
||||
- Do not edit commits that come before the merge commit.
|
||||
- During a squash/fixup, use `exec make -C build unittest` between each
|
||||
pick/edit/reword.
|
||||
|
||||
### Stages: WIP, RFC, RDY
|
||||
|
||||
@ -121,6 +124,11 @@ Use this commit-message format for coverity fixes:
|
||||
|
||||
where `<id>` is the Coverity ID (CID). For example see [#804](https://github.com/neovim/neovim/pull/804).
|
||||
|
||||
### PVS-Studio
|
||||
|
||||
Run `scripts/pvscheck.sh` to check the codebase with [PVS
|
||||
Studio](https://www.viva64.com/en/pvs-studio/).
|
||||
|
||||
Reviewing
|
||||
---------
|
||||
|
||||
|
||||
@ -9,8 +9,7 @@ Nvim API *API* *api*
|
||||
Nvim exposes a powerful API that can be used by plugins and external processes
|
||||
via |msgpack-rpc|, Lua and VimL (|eval-api|).
|
||||
|
||||
Nvim can also be embedded in C applications as libnvim, so the application
|
||||
can control the embedded instance by calling the C API directly.
|
||||
Applications can also embed libnvim to work with the C API directly.
|
||||
|
||||
==============================================================================
|
||||
API Types *api-types*
|
||||
@ -54,6 +53,28 @@ error_types Possible error types returned by API functions
|
||||
|
||||
External programs ("clients") can use the metadata to discover the |rpc-api|.
|
||||
|
||||
==============================================================================
|
||||
API contract *api-contract*
|
||||
|
||||
The API is made of functions and events. Clients call functions like those
|
||||
described at |api-global|, and may "attach" in order to receive rich events,
|
||||
described at |rpc-remote-ui|.
|
||||
|
||||
As Nvim develops, its API may change only according the following "contract":
|
||||
|
||||
- New functions and events may be added.
|
||||
- Any such extensions are OPTIONAL: old clients may ignore them.
|
||||
- Function signatures will NOT CHANGE (after release).
|
||||
- Functions introduced in the development (unreleased) version MAY CHANGE.
|
||||
(Clients can dynamically check `api_prerelease`, etc. |api-metadata|)
|
||||
- Event parameters will not be removed or reordered (after release).
|
||||
- Events may be EXTENDED: new parameters may be added.
|
||||
- New items may be ADDED to map/list parameters/results of functions and
|
||||
events.
|
||||
- Any such new items are OPTIONAL: old clients may ignore them.
|
||||
- Existing items will not be removed (after release).
|
||||
- Deprecated functions will not be removed until Nvim version 2.0
|
||||
|
||||
==============================================================================
|
||||
Buffer highlighting *api-highlights*
|
||||
|
||||
|
||||
@ -6,22 +6,20 @@
|
||||
|
||||
Development of Nvim. *development*
|
||||
|
||||
1. Design goals |design-goals|
|
||||
2. Design decisions |design-decisions|
|
||||
1. Design goals |design-goals|
|
||||
2. Developer guidelines |dev-help|
|
||||
|
||||
Nvim is open source software. Everybody is encouraged to contribute.
|
||||
https://github.com/neovim/neovim/blob/master/CONTRIBUTING.md
|
||||
|
||||
See src/nvim/README.md for a high-level overview of the source code:
|
||||
https://github.com/neovim/neovim/blob/master/src/nvim/README.md
|
||||
See src/nvim/README.md for an overview of the source code.
|
||||
|
||||
==============================================================================
|
||||
1. Design goals *design-goals*
|
||||
Design goals *design-goals*
|
||||
|
||||
Most important things come first (roughly).
|
||||
|
||||
Note that quite a few items are contradicting. This is intentional. A
|
||||
balance must be found between them.
|
||||
Note that some items conflict; this is intentional. A balance must be found.
|
||||
|
||||
|
||||
NVIM IS... IMPROVED *design-improved*
|
||||
@ -41,7 +39,7 @@ completely different editor. Extensions are done with a "Vi spirit".
|
||||
- There are many first-time and inexperienced Vim users. Make it easy for
|
||||
them to start using Vim and learn more over time.
|
||||
- There is no limit to the features that can be added. Selecting new features
|
||||
is one based on (1) what users ask for, (2) how much effort it takes to
|
||||
is based on (1) what users ask for, (2) how much effort it takes to
|
||||
implement and (3) someone actually implementing it.
|
||||
|
||||
|
||||
@ -56,20 +54,14 @@ Vim tries to help as many users on as many platforms as possible.
|
||||
- Support many compilers and libraries. Not everybody is able or allowed to
|
||||
install another compiler or GUI library.
|
||||
- People switch from one platform to another, and from GUI to terminal
|
||||
version. Features should be present in all versions, or at least in as many
|
||||
as possible with a reasonable effort. Try to avoid that users must switch
|
||||
between platforms to accomplish their work efficiently.
|
||||
- That a feature is not possible on some platforms, or only possible on one
|
||||
platform, does not mean it cannot be implemented. [This intentionally
|
||||
contradicts the previous item, these two must be balanced.]
|
||||
version. Features should be present in all versions.
|
||||
|
||||
|
||||
NVIM IS... WELL DOCUMENTED *design-documented*
|
||||
|
||||
- A feature that isn't documented is a useless feature. A patch for a new
|
||||
feature must include the documentation.
|
||||
- Documentation should be comprehensive and understandable. Using examples is
|
||||
recommended.
|
||||
- Documentation should be comprehensive and understandable. Use examples.
|
||||
- Don't make the text unnecessarily long. Less documentation means that an
|
||||
item is easier to find.
|
||||
- Do not prefix doc-tags with "nvim-". Use |vim_diff.txt| to document
|
||||
@ -77,12 +69,12 @@ NVIM IS... WELL DOCUMENTED *design-documented*
|
||||
to mark a specific feature. No other distinction is necessary.
|
||||
- If a feature is removed, delete its doc entry and move its tag to
|
||||
|vim_diff.txt|.
|
||||
- Move deprecated features to |deprecated.txt|.
|
||||
|
||||
|
||||
NVIM IS... HIGH SPEED AND SMALL IN SIZE *design-speed-size*
|
||||
|
||||
Using Vim must not be a big attack on system resources. Keep it small and
|
||||
fast.
|
||||
Keep Nvim small and fast.
|
||||
- Computers are becoming faster and bigger each year. Vim can grow too, but
|
||||
no faster than computers are growing. Keep Vim usable on older systems.
|
||||
- Many users start Vim from a shell very often. Startup time must be short.
|
||||
@ -118,13 +110,14 @@ NVIM IS... NOT *design-not*
|
||||
|
||||
Nvim is not an operating system; instead it should be composed with other
|
||||
tools or hosted as a component. Marvim once said: "Unlike Emacs, Nvim does not
|
||||
include the kitchen sink... but you can use it for plumbing."
|
||||
include the kitchen sink... but it's good for plumbing."
|
||||
|
||||
|
||||
==============================================================================
|
||||
2. Design decisions *design-decisions*
|
||||
Developer guidelines *dev-help*
|
||||
|
||||
JARGON *dev-jargon*
|
||||
|
||||
JARGON *dev-jargon*
|
||||
|
||||
API client ~
|
||||
All external UIs and remote plugins (as opposed to regular Vim plugins) are
|
||||
@ -150,15 +143,14 @@ the xterm window, a window inside Vim to view a buffer.
|
||||
To avoid confusion, other items that are sometimes called window have been
|
||||
given another name. Here is an overview of the related items:
|
||||
|
||||
screen The whole display. For the GUI it's something like 1024x768
|
||||
pixels. The Vim shell can use the whole screen or part of it.
|
||||
screen The whole display.
|
||||
shell The Vim application. This can cover the whole screen (e.g.,
|
||||
when running in a console) or part of it (xterm or GUI).
|
||||
window View on a buffer. There can be several windows in Vim,
|
||||
together with the command line, menubar, toolbar, etc. they
|
||||
fit in the shell.
|
||||
|
||||
PROVIDERS *dev-provider*
|
||||
PROVIDERS *dev-provider*
|
||||
|
||||
A goal of Nvim is to allow extension of the editor without special knowledge
|
||||
in the core. But some Vim components are too tightly coupled; in those cases
|
||||
@ -202,7 +194,7 @@ Python host isn't installed then the plugin will "think" it is running in
|
||||
a Vim compiled without the |+python| feature.
|
||||
|
||||
|
||||
API *dev-api*
|
||||
API *dev-api*
|
||||
|
||||
Use this pattern to name new API functions:
|
||||
nvim_{thing}_{action}_{arbitrary-qualifiers}
|
||||
@ -233,4 +225,23 @@ _not_ a Buffer). The common {action} "list" indicates that it lists all
|
||||
bufs (plural) in the global context.
|
||||
|
||||
|
||||
EXTERNAL UI *dev-ui*
|
||||
|
||||
External UIs should be aware of the |api-contract|. In particular, future
|
||||
versions of Nvim may add optional, new items to existing events. The API is
|
||||
strongly backwards-compatible, but clients must not break if new fields are
|
||||
added to existing events.
|
||||
|
||||
External UIs are expected to implement some common features.
|
||||
|
||||
- Users may want to configure UI-specific options. The UI should publish the
|
||||
|GUIEnter| autocmd after attaching to Nvim: >
|
||||
doautocmd GUIEnter
|
||||
- Options can be monitored for changes by the |OptionSet| autocmd. E.g. if the
|
||||
user sets the 'guifont' option, this autocmd notifies channel 42: >
|
||||
autocmd OptionSet guifont call rpcnotify(42, 'option-changed', 'guifont', &guifont)
|
||||
- cursor-shape change: 'guicursor' properties are sent in the mode_info_set UI
|
||||
event.
|
||||
|
||||
|
||||
vim:tw=78:ts=8:ft=help:norl:
|
||||
|
||||
@ -720,9 +720,6 @@ special key: >
|
||||
Don't type a real <Esc>, Vim will recognize the key code and replace it with
|
||||
<F1> anyway.
|
||||
|
||||
Another problem may be that when keeping ALT or Meta pressed the terminal
|
||||
prepends ESC instead of setting the 8th bit. See |:map-alt-keys|.
|
||||
|
||||
*recursive_mapping*
|
||||
If you include the {lhs} in the {rhs} you have a recursive mapping. When
|
||||
{lhs} is typed, it will be replaced with {rhs}. When the {lhs} which is
|
||||
@ -762,46 +759,14 @@ in the original Vi, you would get back the text before the first undo).
|
||||
|
||||
1.10 MAPPING ALT-KEYS *:map-alt-keys*
|
||||
|
||||
In the GUI Vim handles the Alt key itself, thus mapping keys with ALT should
|
||||
always work. But in a terminal Vim gets a sequence of bytes and has to figure
|
||||
out whether ALT was pressed or not.
|
||||
|
||||
By default Vim assumes that pressing the ALT key sets the 8th bit of a typed
|
||||
character. Most decent terminals can work that way, such as xterm, aterm and
|
||||
rxvt. If your <A-k> mappings don't work it might be that the terminal is
|
||||
prefixing the character with an ESC character. But you can just as well type
|
||||
ESC before a character, thus Vim doesn't know what happened (except for
|
||||
checking the delay between characters, which is not reliable).
|
||||
|
||||
As of this writing, some mainstream terminals like gnome-terminal and konsole
|
||||
use the ESC prefix. There doesn't appear a way to have them use the 8th bit
|
||||
instead. Xterm should work well by default. Aterm and rxvt should work well
|
||||
when started with the "--meta8" argument. You can also tweak resources like
|
||||
"metaSendsEscape", "eightBitInput" and "eightBitOutput".
|
||||
|
||||
On the Linux console, this behavior can be toggled with the "setmetamode"
|
||||
command. Bear in mind that not using an ESC prefix could get you in trouble
|
||||
with other programs. You should make sure that bash has the "convert-meta"
|
||||
option set to "on" in order for your Meta keybindings to still work on it
|
||||
(it's the default readline behavior, unless changed by specific system
|
||||
configuration). For that, you can add the line: >
|
||||
|
||||
set convert-meta on
|
||||
|
||||
to your ~/.inputrc file. If you're creating the file, you might want to use: >
|
||||
|
||||
$include /etc/inputrc
|
||||
|
||||
as the first line, if that file exists on your system, to keep global options.
|
||||
This may cause a problem for entering special characters, such as the umlaut.
|
||||
Then you should use CTRL-V before that character.
|
||||
|
||||
Bear in mind that convert-meta has been reported to have troubles when used in
|
||||
UTF-8 locales. On terminals like xterm, the "metaSendsEscape" resource can be
|
||||
toggled on the fly through the "Main Options" menu, by pressing Ctrl-LeftClick
|
||||
on the terminal; that's a good last resource in case you want to send ESC when
|
||||
using other applications but not when inside VIM.
|
||||
|
||||
In the GUI Nvim handles the |ALT| key itself, thus mapping keys with ALT
|
||||
should always work. But in a terminal Nvim gets a sequence of bytes and has
|
||||
to figure out whether ALT was pressed. Terminals may use ESC to indicate that
|
||||
ALT was pressed. If ESC is followed by a {key} within 'ttimeoutlen'
|
||||
milliseconds, the ESC is interpreted as:
|
||||
<ALT-{key}>
|
||||
otherwise it is interpreted as two key presses:
|
||||
<ESC> {key}
|
||||
|
||||
1.11 MAPPING AN OPERATOR *:map-operator*
|
||||
|
||||
|
||||
@ -4803,10 +4803,7 @@ guisp={color-name} *highlight-guisp*
|
||||
Black White
|
||||
Orange Purple Violet
|
||||
|
||||
In the Win32 GUI version, additional system colors are available. See
|
||||
|win32-colors|.
|
||||
|
||||
You can also specify a color by its Red, Green and Blue values.
|
||||
You can also specify a color by its RGB (red, green, blue) values.
|
||||
The format is "#rrggbb", where
|
||||
"rr" is the Red value
|
||||
"gg" is the Green value
|
||||
|
||||
Loading…
Reference in New Issue
Block a user