Update documentation about adding new Vim plugins to nixpkgs

1 files changed, 17 insertions, 10 deletions

diff --git a/doc/languages-frameworks/vim.section.md b/doc/languages-frameworks/vim.section.md
index c450a09f7bd..c75b6bd32fd 100644
--- a/doc/languages-frameworks/vim.section.md
+++ b/doc/languages-frameworks/vim.section.md
@@ -235,15 +235,23 @@ Sample output2:
 
 ## Adding new plugins to nixpkgs
 
-In `pkgs/misc/vim-plugins/vim-plugin-names` we store the plugin names
-for all vim plugins we automatically generate plugins for.
-The format of this file `github username/github repository`:
-For example https://github.com/scrooloose/nerdtree becomes `scrooloose/nerdtree`.
-After adding your plugin to this file run the `./update.py` in the same folder.
-This will updated a file called `generated.nix` and make your plugin accessible in the
-`vimPlugins` attribute set (`vimPlugins.nerdtree` in our example).
-If additional steps to the build process of the plugin are required, add an
-override to the `pkgs/misc/vim-plugins/default.nix` in the same directory.
+Nix expressions for Vim plugins are stored in [pkgs/misc/vim-plugins](/pkgs/misc/vim-plugins). For the vast majority of plugins, Nix expressions are automatically generated by running [`./update.py`](/pkgs/misc/vim-plugins/update.py). This creates a [generated.nix](/pkgs/misc/vim-plugins/generated.nix) file based on the plugins listed in [vim-plugin-names](/pkgs/misc/vim-plugins/vim-plugin-names). Plugins are listed in alphabetical order in `vim-plugin-names` using the format `[github username]/[repository]`. For example https://github.com/scrooloose/nerdtree becomes `scrooloose/nerdtree`.
+
+Some plugins require overrides in order to function properly. Overrides are placed in [overrides.nix](/pkgs/misc/vim-plugins/overrides.nix). Overrides are most often required when a plugin requires some dependencies, or extra steps are required during the build process. For example `deoplete-fish` requires both `deoplete-nvim` and `vim-fish`, and so the following override was added:
+```nix
+deoplete-fish = super.deoplete-fish.overrideAttrs(old: {
+  dependencies = with super; [ deoplete-nvim vim-fish ];
+});
+```
+
+Sometimes plugins require an override that must be changed when the plugin is updated. This can cause issues when Vim plugins are auto-updated but the associated override isn't updated. For these plugins, the override should be written so that it specifies all information required to install the plugin, and running `./update.py` doesn't change the derivation for the plugin. Manually updating the override is required to update these types of plugins. An example of such a plugin is `LanguageClient-neovim`.
+
+To add a new plugin:
+
+  1. run `./update.py` and create a commit named "vimPlugins: Update",
+  2. add the new plugin to [vim-plugin-names](/pkgs/misc/vim-plugins/vim-plugin-names) and add overrides if required to [overrides.nix](/pkgs/misc/vim-plugins/overrides.nix),
+  3. run `./update.py` again and create a commit named "vimPlugins.[name]: init at [version]" (where `name` and `version` can be found in [generated.nix](/pkgs/misc/vim-plugins/generated.nix)), and
+  4. create a pull request.
 
 ## Important repositories
 
@@ -252,4 +260,3 @@ override to the `pkgs/misc/vim-plugins/default.nix` in the same directory.
 
 - [vim2nix](https://github.com/MarcWeber/vim-addon-vim2nix) which generates the
   .nix code
-