5 files changed, 61 insertions, 6 deletions
diff --git a/doc/builders/special/fhs-environments.section.md b/doc/builders/special/fhs-environments.section.md
index 146ded532404..43dc99b7c18f 100644
--- a/doc/builders/special/fhs-environments.section.md
+++ b/doc/builders/special/fhs-environments.section.md
@@ -18,6 +18,8 @@
         Additional commands to be executed for finalizing the derivation with runner script.
 - `runScript`
         A command that would be executed inside the sandbox and passed all the command line arguments. It defaults to `bash`.
+- `profile`
+        Optional script for `/etc/profile` within the sandbox.
 
 One can create a simple environment using a `shell.nix` like that:
 
diff --git a/doc/contributing/coding-conventions.chapter.md b/doc/contributing/coding-conventions.chapter.md
index 240260105c3b..7199fc63c8d0 100644
--- a/doc/contributing/coding-conventions.chapter.md
+++ b/doc/contributing/coding-conventions.chapter.md
@@ -520,7 +520,7 @@ If you do need to do create this sort of patch file, one way to do so is with gi
 4. Use git to create a diff, and pipe the output to a patch file:
 
     ```ShellSession
-    $ git diff > nixpkgs/pkgs/the/package/0001-changes.patch
+    $ git diff -a > nixpkgs/pkgs/the/package/0001-changes.patch
     ```
 
 If a patch is available online but does not cleanly apply, it can be modified in some fixed ways by using additional optional arguments for `fetchpatch`:
@@ -537,7 +537,13 @@ Note that because the checksum is computed after applying these effects, using o
 
 Tests are important to ensure quality and make reviews and automatic updates easy.
 
-Nix package tests are a lightweight alternative to [NixOS module tests](https://nixos.org/manual/nixos/stable/#sec-nixos-tests). They can be used to create simple integration tests for packages while the module tests are used to test services or programs with a graphical user interface on a NixOS VM. Unittests that are included in the source code of a package should be executed in the `checkPhase`.
+The following types of tests exists:
+
+* [NixOS **module tests**](https://nixos.org/manual/nixos/stable/#sec-nixos-tests), which spawn one or more NixOS VMs. They exercise both NixOS modules and the packaged programs used within them. For example, a NixOS module test can start a web server VM running the `nginx` module, and a client VM running `curl` or a graphical `firefox`, and test that they can talk to each other and display the correct content.
+* Nix **package tests** are a lightweight alternative to NixOS module tests. They should be used to create simple integration tests for packages, but cannot test NixOS services, and some programs with graphical user interfaces may also be difficult to test with them.
+* The **`checkPhase` of a package**, which should execute the unit tests that are included in the source code of a package.
+
+Here in the nixpkgs manual we describe mostly _package tests_; for _module tests_ head over to the corresponding [section in the NixOS manual](https://nixos.org/manual/nixos/stable/#sec-nixos-tests).
 
 ### Writing package tests {#ssec-package-tests-writing}
 
@@ -602,3 +608,23 @@ Here are examples of package tests:
 - [Spacy annotation test](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/python-modules/spacy/annotation-test/default.nix)
 - [Libtorch test](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/libraries/science/math/libtorch/test/default.nix)
 - [Multiple tests for nanopb](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/libraries/nanopb/default.nix)
+
+### Linking NixOS module tests to a package {#ssec-nixos-tests-linking}
+
+Like [package tests](#ssec-package-tests-writing) as shown above, [NixOS module tests](https://nixos.org/manual/nixos/stable/#sec-nixos-tests) can also be linked to a package, so that the tests can be easily run when changing the related package.
+
+For example, assuming we're packaging `nginx`, we can link its module test via `passthru.tests`:
+
+```nix
+{ stdenv, lib, nixosTests }:
+
+stdenv.mkDerivation {
+  ...
+
+  passthru.tests = {
+    nginx = nixosTests.nginx;
+  };
+
+  ...
+}
+```
diff --git a/doc/languages-frameworks/python.section.md b/doc/languages-frameworks/python.section.md
index 847a41cf23c3..53df328f8d48 100644
--- a/doc/languages-frameworks/python.section.md
+++ b/doc/languages-frameworks/python.section.md
@@ -8,7 +8,7 @@
 
 Several versions of the Python interpreter are available on Nix, as well as a
 high amount of packages. The attribute `python3` refers to the default
-interpreter, which is currently CPython 3.8. The attribute `python` refers to
+interpreter, which is currently CPython 3.9. The attribute `python` refers to
 CPython 2.7 for backwards-compatibility. It is also possible to refer to
 specific versions, e.g. `python38` refers to CPython 3.8, and `pypy` refers to
 the default PyPy interpreter.
@@ -839,7 +839,7 @@ sets are
 and the aliases
 
 * `pkgs.python2Packages` pointing to `pkgs.python27Packages`
-* `pkgs.python3Packages` pointing to `pkgs.python38Packages`
+* `pkgs.python3Packages` pointing to `pkgs.python39Packages`
 * `pkgs.pythonPackages` pointing to `pkgs.python2Packages`
 
 #### `buildPythonPackage` function {#buildpythonpackage-function}
diff --git a/doc/languages-frameworks/rust.section.md b/doc/languages-frameworks/rust.section.md
index f5c664bec20e..f17e1ba8d8f0 100644
--- a/doc/languages-frameworks/rust.section.md
+++ b/doc/languages-frameworks/rust.section.md
@@ -144,7 +144,7 @@ rustPlatform.buildRustPackage rec {
     outputHashes = {
       "finalfusion-0.14.0" = "17f4bsdzpcshwh74w5z119xjy2if6l2wgyjy56v621skr2r8y904";
     };
-  }
+  };
 
   # ...
 }
diff --git a/doc/languages-frameworks/vim.section.md b/doc/languages-frameworks/vim.section.md
index e170591605cf..26a01a89aa51 100644
--- a/doc/languages-frameworks/vim.section.md
+++ b/doc/languages-frameworks/vim.section.md
@@ -120,7 +120,7 @@ After that you can install your special grafted `myVim` or `myNeovim` packages.
 
 If one of your favourite plugins isn't packaged, you can package it yourself:
 
-```
+```nix
 { config, pkgs, ... }:
 
 let
@@ -154,6 +154,33 @@ in
 }
 ```
 
+### Specificities for some plugins
+#### Tree sitter
+
+By default `nvim-treesitter` encourages you to download, compile and install
+the required tree-sitter grammars at run time with `:TSInstall`. This works
+poorly on NixOS.  Instead, to install the `nvim-treesitter` plugins with a set
+of precompiled grammars, you can use `nvim-treesitter.withPlugins` function:
+
+```nix
+(pkgs.neovim.override {
+  configure = {
+    packages.myPlugins = with pkgs.vimPlugins; {
+      start = [
+        (nvim-treesitter.withPlugins (
+          plugins: with plugins; [
+            tree-sitter-nix
+            tree-sitter-python
+          ]
+        ))
+      ];
+    };
+  };
+})
+```
+
+To enable all grammars packaged in nixpkgs, use `(pkgs.vimPlugins.nvim-treesitter.withPlugins (plugins: pkgs.tree-sitter.allGrammars))`.
+
 ## Managing plugins with vim-plug {#managing-plugins-with-vim-plug}
 
 To use [vim-plug](https://github.com/junegunn/vim-plug) to manage your Vim