document the reasons

montanalow · montanalow · commit ed49732fd5a5 · 2023-12-18T17:15:17.000-08:00
diff --git a/pgml-extension/requirements.txt b/pgml-extension/requirements.txt
@@ -1,11 +1,17 @@
-# The immediate dependencies of PostgresML are maintained here.
+# If you update this file, `pip freeze` the full locked requirements as well to prevent
+# future dependency incompatibility on all supported platforms. We'd use Poetry or some
+# other sane lockfile resolution mechanism other than pip, except we have to maintain
+# this isn't really a Python project, so Poetry conventions don't work, and we need
+# different dependencies on platforms that have different hardware acceleration.
+
+# Only the immediate dependencies of PostgresML are maintained here.
 # See requirements.linux.txt or requirements.macos.txt for complete and locked versions.
 
 # Python 3.12 can't currently resolve all dependencies:
 # catboost fails to build
 # virtualenv -p python3.11 pgml-venv
 
-# Specifically locked to avoid known bugs
+# These packages are specifically locked to avoid known bugs
 pyarrow==11.0.0 # newer versions cause Postgres segfaults on OOM
 
 # ML
