docs(o11y): revise terminology to remove 'gate' metaphor

Author: chalmerlowe

packages/google-api-core/google/api_core/observability/options.py

@@ -97,7 +97,7 @@ def resolve_feature_flags(
     Behavior depends on whether the `env_var` name contains "EXPERIMENTAL":
 
     - **Experimental Path** (env_var contains "EXPERIMENTAL"):
-      Strict gating. Requires the environment variable to be explicitly 'true'.
+      Strict control. Requires the environment variable to be explicitly 'true'.
       If a programmatic provider is passed but the environment variable is not 'true',
       raises ValueError (Fail Fast).
 
@@ -114,7 +114,7 @@ def resolve_feature_flags(
         bool: True if the feature is resolved to enabled, False otherwise.
 
     Raises:
-        ValueError: If a provider is passed for an experimental feature without opening the gate.
+        ValueError: If a provider is provided for an experimental feature without enabling the experimental environment variable.
     """
 
     # Check for programmatic feature provider
@@ -125,10 +125,10 @@ def resolve_feature_flags(
 
     # EXPERIMENTAL PATH:
     # Resolution Hierarchy:
-    #   1. EXPERIMENTAL Gate
-    #   2. Fail Fast if Provider present but EXPERIMENTAL Gate is closed
+    #   1. EXPERIMENTAL Environment Variable
+    #   2. Fail Fast if Provider present but EXPERIMENTAL Environment Variable is not enabled
     if "EXPERIMENTAL" in env_var:
-        # Fail Fast if provider present but gate is closed
+        # Fail Fast if provider present but experimental environment variable is not enabled
         if env_var_setting is not True and has_provider:
             raise ValueError(
                 f"Experimental feature requires {env_var} to be set to 'true' to use programmatic providers."

packages/google-api-core/tests/unit/observability/test_options.py

@@ -107,11 +107,11 @@ def test_resolve_feature_flags_ga_enabled_via_env():
     assert result is True
 
 
-@pytest.mark.parametrize("gate_value", [None, False])
-def test_resolve_feature_flags_exp_blocked_with_provider_fails_fast(gate_value):
-    """Verify that passing a provider to an experimental feature without the gate raises ValueError."""
-    # Setup: Experimental env var is set to gate_value (None means not set)
-    set_test_env_override("GOOGLE_SDK_EXPERIMENTAL_PYTHON_TRACING_ENABLED", gate_value)
+@pytest.mark.parametrize("exp_env_state", [None, False], ids=["missing", "disabled"])
+def test_resolve_feature_flags_exp_blocked_with_provider_fails_fast(exp_env_state):
+    """Verify that passing a provider to an experimental feature raises ValueError if the experimental environment variable is disabled or missing."""
+    # Setup: Experimental env var is set to exp_env_state (None means not set)
+    set_test_env_override("GOOGLE_SDK_EXPERIMENTAL_PYTHON_TRACING_ENABLED", exp_env_state)
     client_options = {"tracer_provider": object()}
 
     # Action & Assertion
@@ -124,7 +124,7 @@ def test_resolve_feature_flags_exp_blocked_with_provider_fails_fast(gate_value):
 
 
 def test_resolve_feature_flags_exp_enabled_with_provider():
-    """Verify that experimental feature is enabled if gate is True, even with provider."""
+    """Verify that experimental feature is enabled if the experimental environment variable is enabled and a provider is provided."""
     set_test_env_override("GOOGLE_SDK_EXPERIMENTAL_PYTHON_TRACING_ENABLED", True)
     client_options = {"tracer_provider": object()}
 
@@ -137,7 +137,7 @@ def test_resolve_feature_flags_exp_enabled_with_provider():
 
 
 def test_resolve_feature_flags_ga_enabled_via_provider():
-    """Verify that a GA feature is enabled if a provider is passed, bypassing env var."""
+    """Verify that a GA feature is enabled if a provider is provided, ignoring the environment variable."""
     # Env var is False, but provider is present
     set_test_env_override("GOOGLE_SDK_PYTHON_TRACING_ENABLED", False)
     client_options = {"tracer_provider": object()}
@@ -154,7 +154,7 @@ def test_resolve_feature_flags_ga_enabled_via_provider():
     "env_val", [None, False], ids=["env_not_set", "env_explicit_false"]
 )
 def test_resolve_feature_flags_ga_fallback_to_false(env_val):
-    """Verify that a GA feature returns False if no flags are present."""
+    """Verify that a GA feature is disabled if neither a provider is provided nor the environment variable is enabled."""
     set_test_env_override("GOOGLE_SDK_PYTHON_TRACING_ENABLED", env_val)
     result = options.resolve_feature_flags(
         env_var="GOOGLE_SDK_PYTHON_TRACING_ENABLED",