Tighten extras policy and CI validation (#318)

* Add extras guardrail check and docs/release notes

* Align gcsfs pin with main for extras subset check

Author: jdbcode

.github/workflows/ci-build.yml

@@ -24,6 +24,39 @@ on:
   workflow_dispatch:
 
 jobs:
+  validate-metadata:
+    name: "validate package metadata"
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v6
+    - name: Set up Python 3.11
+      uses: actions/setup-python@v6
+      with:
+        python-version: "3.11"
+    - name: Validate optional dependency relationships
+      run: |
+        python - <<'PY'
+        import tomllib
+        from pathlib import Path
+
+        pyproject = Path("pyproject.toml")
+        data = tomllib.loads(pyproject.read_text())
+        optional = data["project"]["optional-dependencies"]
+
+        dataflow = set(optional.get("dataflow", []))
+        examples = set(optional.get("examples", []))
+
+        missing = sorted(dataflow - examples)
+        if missing:
+          print("The [examples] extra must include all [dataflow] dependencies.")
+          print("Missing from examples:")
+          for dep in missing:
+            print(f"- {dep}")
+          raise SystemExit(1)
+
+        print("Optional dependency check passed: dataflow is a subset of examples.")
+        PY
+
   build:
     name: "python ${{ matrix.python-version }} tests"
     runs-on: ubuntu-latest

docs/releasing.md

@@ -59,3 +59,13 @@ Use this to finalize a tested release branch.
 - Avoid creating stable releases directly from `main`; use the release branch path.
 - If a stable release was published by mistake, coordinate with maintainers before
   deleting tags or editing release records.
+
+## Dependency extras guardrails
+
+- `dataflow` is intended for production export workflows.
+- `examples` may include `dataflow` dependencies plus any additional packages used
+   by user-facing examples.
+- Keep `examples` explicit (do not use self-referential extras like
+   `xee[dataflow]` inside `project.optional-dependencies`).
+- CI enforces that every dependency in `dataflow` is also present in `examples`
+   (subset check in `.github/workflows/ci-build.yml`).

pyproject.toml

@@ -49,8 +49,14 @@ dataflow = [
   "gcsfs<=2026.4.0",
   "xarray-beam",
 ]
+# Keep examples equivalent to dataflow, but avoid self-referential extras
+# ("xee[dataflow]") which can confuse dependency resolvers.
 examples = [
-  "xee[dataflow]",
+  "absl-py",
+  "apache-beam[gcp]",
+  "gcsfs<=2026.4.0",
+  "matplotlib",
+  "xarray-beam",
 ]
 
 [project.urls]