Add first draft of explanations for new tests

explanations/duplicate-check-inputs.md

@@ -0,0 +1,3 @@
+In Python package derivations, `propagatedBuildInputs` is used to list depedencies that are required to be available at run time, in addition to build time. `checkInputs` lists dependencies that are required specifically during the `checkPhase
+
+All dependencies from `propagatedBuildInputs` are available during `checkPhase`, so there is no need to duplicate them in the `checkInputs`.

explanations/python-explicit-check-phase.md

@@ -0,0 +1,42 @@
+Nixpkgs contains a `pytestCheckHook` that can automatically run tests using pytest.
+
+For example, rather than
+
+```
+buildPythonPackage {
+    checkInputs = [ pytest ...];
+    checkPhase = ''
+      pytest
+    '';
+};
+```
+
+Consider instead using
+```
+buildPythonPackage {
+    checkInputs = [ pytestCheckHook ...];
+};
+
+```
+
+Also note that many flags that you might want to pass to `pytest` can be passed automatically through `pytestCheckHook`.
+
+`buibuildPythonPackage` accepts:
+
+ - `disabledTests` to disable particular pytest tests.
+ - `pytestFlagsArray` to pass flags to pytest
+
+
+Here's a complete example using `pytestCheckHook`, `pytestFlagsArray`, and `disabledTests`:
+
+```
+buildPythonPackage {
+  ..
+  checkInputs = [ pytestCheckHook ];
+  pytestFlagsArray = [ "-o cache_dir=$(mktemp -d)" ];
+  disabledTests = [
+    "test_tv_inpainting"
+    "test_diffcp_sdp_example"
+  ];
+}
+```

explanations/python-imports-check-typo.md

@@ -0,0 +1,16 @@
+Not all python packages include tests. However it should be possible, at a minimum, to "smoke test" every python package my simply checking that the modules it declares can be `import`ed.
+
+For example, `pythonImportsCheck` can be used like this:
+```
+buildPythonPackage {
+  name = "mymodule";
+  src = ...
+
+  pythonImportsCheck = [
+    "mymodule.submodule1"
+    "mymodule.submodule2"
+  ];
+}
+```
+
+Note: it's easy to make a typo in the key `"pythonImportsCheck"` here, so watch out for that.

explanations/python-include-tests.md

@@ -0,0 +1,7 @@
+Some level of testing should be done for each python derivation.
+
+It may be necessary to:
+
+  (a) Tell `pytest` or `pytestCheckHook` where to find the tests included in the package.
+  (b) Check if the GitHub Repo contains tests but they are not shipped with Pypi. If so please switch to `fetchFromGitHub`.
+  (c) If the Packages does not contain any tests add `doCheck = false;` and a `pythonImportsCheck` as a "smoke test".

explanations/python-inconsistent-interpreters.md

@@ -0,0 +1,34 @@
+Each python derivation in nixpkgs should take its inputs in such a way that it
+can be properly built for multiple different python interpreters.
+
+For example, the following is incorrect:
+
+```
+{ lib
+, buildPythonPackage
+, python3Packages
+}:
+
+buildPythonPackage rec {
+  pname = "mypackage";
+  ...
+  propagatedBuildInputs = [ python3Packages.numpy ];
+}
+```
+
+Instead, it should be:
+
+```
+{ lib
+, buildPythonPackage
+, numpy
+}:
+
+buildPythonPackage rec {
+  pname = "mypackage";
+  ...
+  propagatedBuildInputs = [ numpy ];
+}
+```
+
+This design will allow nixpkgs to ensure that the version of python pulled in by `numpy` is the same as the version of python that the package is built for.