Merge pull request #322556 from hercules-ci/explain-test-cabalSdist

doc: Explain cabalSdist test

pkgs/test/haskell/cabalSdist/default.nix

@@ -12,6 +12,11 @@ lib.recurseIntoAttrs rec {
 
   localFromCabalSdist = haskellPackages.buildFromCabalSdist localRaw;
 
+  # NOTE: ./local refers to the "./." path in `./local/generated.nix`.
+  # This test makes sure that localHasNoDirectReference can actually fail if
+  # it doesn't do anything. If this test fails, either the test setup was broken,
+  # or Haskell packaging has changed the way `src` is treated in such a way that
+  # either the test or the design of `buildFromCabalSdist` needs to be reconsidered.
   assumptionLocalHasDirectReference = runCommand "localHasDirectReference" {
     drvPath = builtins.unsafeDiscardOutputDependency localRaw.drvPath;
   } ''

pkgs/test/haskell/cabalSdist/local/generated.nix

@@ -3,7 +3,7 @@
 mkDerivation {
   pname = "local";
   version = "0.1.0.0";
-  src = ./.;
+  src = ./.; # also referred to as ./local in the test; these are the same path constants
   isLibrary = false;
   isExecutable = true;
   executableHaskellDepends = [ base ];