doc: api-contract, CONTRIBUTING.md

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 `<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
 ---------
 
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*
@@ -55,6 +54,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*
 
 Nvim allows plugins to add position-based highlights to buffers. This is
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 <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*
 
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