Elaborate more on Justfile vs Makefile vs GHA

.github/workflows/ci.yml

@@ -2,7 +2,8 @@
 #
 # Core principles:
 # - Everything done here should be easy to replicate locally. Most tasks
-#   should invoke `just <something>`.
+#   should invoke `just <something>`. Read the Justfile for more explanation
+#   of this.
 # - Most additions to this should be extending existing tasks; e.g.
 #   there's places for unit and integration tests already.
 name: CI

Justfile

@@ -3,7 +3,11 @@
 # other tools like `bcvk` which might launch local virtual machines.
 # 
 # See also `Makefile` and `xtask.rs`. Commands which end in `-local`
-# skip containerization or virtualization.
+# skip containerization or virtualization (and typically just proxy `make`).
+#
+# Rules written here are *often* used by the Github Action flows,
+# and should support being configurable where that makes sense (e.g.
+# the `build` rule supports being provided a base image).
 
 # --------------------------------------------------------------------
 

Makefile

@@ -1,19 +1,27 @@
 # Understanding Makefile vs Justfile:
 #
-# This file MUST NOT:
+# This file should primarily *only* involve
+# invoking tools which *do not* have side effects outside
+# of the current working directory. In particular, this file MUST NOT:
 # - Spawn podman or virtualization tools
 # - Invoke `sudo`
 #
 # Stated positively, the code invoked from here is only expected to
 # operate as part of "a build" that results in a bootc binary
 # plus data files. The two key operations are `make`
-# and `make install`.
+# and `make install`. As this is Rust, the generated binaries are in
+# the current directory under `target/` by default. Some rules may place
+# other generated files there.
+#
 # We expect code run from here is (or can be) inside a container with low
 # privileges - running as a nonzero UID even.
 #
 # Understanding Makefile vs xtask.rs: Basically use xtask.rs if what
 # you're doing would turn into a mess of bash code, whether inline here
 # or externally in e.g. ./ci/somebashmess.sh etc.
+#
+# In particular, the Justfile contains rules for things like integration
+# tests which might spawn VMs, etc.
 
 prefix ?= /usr