From 6bc6d94ec8c8f7e291454ebc888c0fa8435908c8 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Mon, 17 Apr 2017 23:52:38 +0200 Subject: [PATCH] doc: api-contract, CONTRIBUTING.md --- CONTRIBUTING.md | 48 ++++++++++++++++++-------------- runtime/doc/api.txt | 25 +++++++++++++++-- runtime/doc/develop.txt | 61 ++++++++++++++++++++++++----------------- runtime/doc/map.txt | 51 ++++++---------------------------- runtime/doc/syntax.txt | 5 +--- 5 files changed, 96 insertions(+), 94 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 52584c25d8..f442ceb672 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 `` 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 --------- diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 2bcc996d8b..a118690876 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -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* diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt index 76ccc42546..0e909aac65 100644 --- a/runtime/doc/develop.txt +++ b/runtime/doc/develop.txt @@ -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: diff --git a/runtime/doc/map.txt b/runtime/doc/map.txt index db349eca71..3ba1ce1f17 100644 --- a/runtime/doc/map.txt +++ b/runtime/doc/map.txt @@ -720,9 +720,6 @@ special key: > Don't type a real , Vim will recognize the key code and replace it with 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 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: + +otherwise it is interpreted as two key presses: + {key} 1.11 MAPPING AN OPERATOR *:map-operator* diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt index f7c2c0e120..50208640ce 100644 --- a/runtime/doc/syntax.txt +++ b/runtime/doc/syntax.txt @@ -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