Rename global flag functions to get_global_*; clarify when to use them

Name the no-user functions get_global_boolean_value / get_global_string_value
/ ... so call sites read as explicitly global, and spell out in the comments
that they're only for flags that genuinely can't be per-user (a toggle that
behaves the same for everyone) - anything per-user must go through the context
so rollouts and experiments can bucket by user.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: aapeliv

app/backend/src/couchers/experimentation.py

@@ -6,8 +6,10 @@
 Two ways to evaluate a flag:
   - Per-user/request: use the CouchersContext methods (context.get_boolean_value, get_string_value,
     etc.), which evaluate for the context's user and own the per-request evaluator cache.
-  - Global (no user/request): use the module-level get_boolean_value / get_string_value / ... below.
-    These evaluate anonymously and are for background jobs and other code with no CouchersContext.
+  - Global (no user/request): use the module-level get_global_boolean_value / get_global_string_value
+    / ... below. Only for flags whose value genuinely can't be per-user - a toggle that behaves the
+    same for everyone. Anything that is or could be per-user must use the context so rollouts and
+    experiments can bucket by user.
 
 Both paths share the enabled / pass-all-gates gating helpers here. setup_experimentation() is called
 once at process startup.
@@ -197,24 +199,27 @@ def _boolean_value(flag_key: str, default: bool, get_evaluator: Callable[[], Gro
     return _feature_value(flag_key, default, get_evaluator)
 
 
-# Global (no user/request) flag evaluation. Mirrors the CouchersContext.get_*_value API but
-# evaluates anonymously: experiments and percentage rollouts are skipped (no user to bucket), so
-# flags fall through to their in-code defaults unless a rule forces a value globally.
-def get_boolean_value(flag_key: str, default: bool) -> bool:
+# Global (no-user) flag evaluation. Use these ONLY for a flag whose value genuinely cannot depend on
+# a user - one that toggles behavior the same way for everyone (e.g. a system-wide kill-switch or
+# behavior toggle). Anything that is or could be per-user must go through the CouchersContext methods
+# instead, so percentage rollouts and experiments can bucket by user. Here there is no user to
+# bucket, so rollouts and experiments are skipped and flags fall through to their in-code defaults
+# unless a rule forces a value globally.
+def get_global_boolean_value(flag_key: str, default: bool) -> bool:
     return _boolean_value(flag_key, default, _global_evaluator)
 
 
-def get_string_value(flag_key: str, default: str) -> str:
+def get_global_string_value(flag_key: str, default: str) -> str:
     return _feature_value(flag_key, default, _global_evaluator)
 
 
-def get_integer_value(flag_key: str, default: int) -> int:
+def get_global_integer_value(flag_key: str, default: int) -> int:
     return _feature_value(flag_key, default, _global_evaluator)
 
 
-def get_float_value(flag_key: str, default: float) -> float:
+def get_global_float_value(flag_key: str, default: float) -> float:
     return _feature_value(flag_key, default, _global_evaluator)
 
 
-def get_object_value[T](flag_key: str, default: T) -> T:
+def get_global_object_value[T](flag_key: str, default: T) -> T:
     return _feature_value(flag_key, default, _global_evaluator)

app/backend/src/couchers/jobs/handlers.py

@@ -839,8 +839,8 @@ def update_badges(payload: empty_pb2.Empty) -> None:
 
         def update_badge(badge_id: str, members: Sequence[int]) -> None:
             badge = get_badge_dict()[badge_id]
-            # a flag that gates a badge is evaluated globally (no per-user request here)
-            if badge.flag is not None and not experimentation.get_boolean_value(badge.flag, default=True):
+            # a badge applies to everyone or no one, so its gate is a global (no-user) flag
+            if badge.flag is not None and not experimentation.get_global_boolean_value(badge.flag, default=True):
                 members = []
             user_ids = session.execute(select(UserBadge.user_id).where(UserBadge.badge_id == badge.id)).scalars().all()
             # in case the user ids don't exist in the db

app/backend/src/tests/test_experimentation.py

@@ -45,12 +45,12 @@ def test_unknown_feature_returns_in_code_default(experimentation_snapshot):
 
 def test_global_evaluation_excluded_from_rollout_gets_feature_default(experimentation_snapshot):
     # global (no-user) evaluation can't bucket into a rollout, so it gets the feature default
-    assert experimentation.get_string_value("rollout_flag", "fallback") == "control"
+    assert experimentation.get_global_string_value("rollout_flag", "fallback") == "control"
 
 
 def test_global_evaluation_gets_global_force_on_flag(experimentation_snapshot):
-    assert experimentation.get_boolean_value("global_flag", default=False) is True
+    assert experimentation.get_global_boolean_value("global_flag", default=False) is True
 
 
 def test_global_evaluation_unknown_feature_returns_in_code_default(experimentation_snapshot):
-    assert experimentation.get_string_value("does_not_exist", "my_default") == "my_default"
+    assert experimentation.get_global_string_value("does_not_exist", "my_default") == "my_default"