add comments for pad (#10235)

#10199

.github/workflows/build-test-nix.jsonnet

@@ -14,6 +14,13 @@ local job = gha.os_matrix(
  name: "Set up Nix",
  uses: "DeterminateSystems/nix-installer-action@main",
  with: {
+ // pysemgrep and osemgrep have networking tests that rely on the
+ // actual internet (i.e. semgrep.dev). When sandbox=false nix builds
+ // everything fine, but all networking tests fail. So we set sandbox
+ // to false here so networking tests succeed
+ //
+ // TODO: disable networking tests for nix? that would be the nix way
+ // of doing things
  "extra-conf": "sandbox = false"
  }
  },
@@ -48,8 +55,6 @@ local job = gha.os_matrix(
 ]);
 {
  name: 'build-test-nix',
- // This is called from tests.jsonnet and release.jsonnet
- // TODO: just make this job a func so no need to use GHA inherit/call
  on: gha.on_classic,
  jobs: {
  job: job,

Makefile

@@ -489,11 +489,18 @@ homebrew-setup:
 # See flake.nix top level comments for more information
 
 # Enter development environment with all dependencies installed
+#
+# The finger stuff here is weird but it's so we can get the user shell and run
+# it in the nix shell. I.e. /usr/bin/zsh or /usr/bin/fish
+# It's really weird because by default makefile overrides $SHELL so this is the
+# only way to get it
 shell:
  $(eval USER_SHELL := $(shell finger ${USER} | grep 'Shell:*' | cut -f3 -d ":"))
  nix develop -c $(USER_SHELL)
 
 # Build targets
+# For all the .?submodules=1 we need because nix is weird:
+# https://github.com/NixOS/nix/issues/4423#issuecomment-791352686
 nix-osemgrep:
  nix build ".?submodules=1#osemgrep"