doc: add more comments

gazelle/python/BUILD.bazel

@@ -18,9 +18,9 @@ go_library(
         "target.go",
     ],
     # NOTE @aignas 2023-12-03: currently gazelle does not support embedding
-    # generated files, which helper.zip is
+    # generated files, but helper.zip is generated by a build rule.
     #
-    # You will get a benign error like:
+    # You will get a benign error like when running gazelle locally:
     # > 8 gazelle: .../rules_python/gazelle/python/lifecycle.go:26:3: pattern helper.zip: matched no files
     #
     # See following for more info:

gazelle/tmp.md

@@ -0,0 +1,16 @@
+Before this change there was a bug in how the parsing helpers were being
+used in case we were using Python 3.11 toolchain, which is using a more
+strict version of the entrypoint template. This change moves the python
+code to a different location to ensure that the top level package is
+something more unique than just "python" and updates the non-bzlmod
+tests to run under 3.11.
+
+We also:
+* Change `.bazelrc` to use explicit `__init__.py` definition to avoid
+  non-reproducible errors in the future.
+* Upgrade `gazelle` to `0.33.0` to be consistent with `bzlmod`.
+* Add a dedicated `gazelle_binary` that uses `DEFAULT_LANGUAGES` *and*
+  `//python`.
+
+Fixes #1589
+