gitlab-experiment 1.6.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e0e710a80403ae390bb66fd552656996ca271891cbc4b2cd758f064538442e5
-  data.tar.gz: 564ea70f574ebabef344f4f428cfad52a6213a35522834956db8eb8073a498e9
+  metadata.gz: b69f6d4aa4d4bbba5b9ef15f5a1d72c84726df5a6ec648cd09761cdc9c997d5b
+  data.tar.gz: ea6f508020bf5941ee7e74647c43052aedf55fa969d8c7dea9d42f86e9b03c8b
 SHA512:
-  metadata.gz: b76011392395d1d0b0e1d7beeec6dc085ea6d7444c231b9dbbdac7f909248cce4ca16f551bb11215b2611ad504a63a593669b31e544d69d1658da0e0ee6004eb
-  data.tar.gz: e9c96959bc9c30b2684bb4eb13665032753f97463f11192b66f2c5592bbe66c29a49663d1fa4a11b2dc64493d10b462dc24b6a6b2380899467df68cdac26ccae
+  metadata.gz: 62690c224599c2c0cbb78a42bdffee6104d5c811faa43027e92a2fd219006e4d0dda7664ee22bdfbb850ad0aa171fa23a82b944a0e667f3b680f2355119c2ae8
+  data.tar.gz: 9b7cfe7e5fcdfce2cfd2826da2974b64c5d61d4989fc87725483e45a9f2547840847ee0f7847d5ebd2e4bcfda13dfe78873404d8c6efd5b60e962b8d6413f56a

data/README.md

@@ -685,11 +685,10 @@ end
 - ✅ Experiment reach stays controlled
 - ✅ Perfect for multi-page experimental experiences
 
-> **Note:** `only_assigned: true` relies on cached assignments. Control variants are cached
-> by default (see [Advanced: Caching Configuration](#advanced-caching-configuration)) so that
-> bucketed control users are included in `only_assigned` tracking. If you set
-> `cache_control: false`, control users will appear unassigned at secondary sites and be
-> excluded from tracking there.
+> **Note:** `only_assigned: true` relies on cached assignments. All rollout
+> strategies cache control variants (see
+> [Advanced: Caching Configuration](#advanced-caching-configuration)) so that bucketed
+> control users are included in `only_assigned` tracking.
 
 **Real-world use cases:**
 - **Post-signup experiences**: Assign at signup, show features throughout the app
@@ -704,7 +703,7 @@ needs.
 
 **Built-in strategies:**
 - [`Percent`](lib/gitlab/experiment/rollout/percent.rb) - Consistent percentage-based assignment (default, recommended)
-- [`Random`](lib/gitlab/experiment/rollout/random.rb) - True random assignment (useful for load testing)
+- [`Random`](lib/gitlab/experiment/rollout/random.rb) - Random assignment on first roll (useful for load testing)
 - [`RoundRobin`](lib/gitlab/experiment/rollout/round_robin.rb) - Cycle through variants (requires caching)
 - [`Base`](lib/gitlab/experiment/rollout.rb) - Useful for building custom rollout strategies
 
@@ -885,13 +884,13 @@ graph TD
     Excluded? -->|No| Segmented?
     Segmented? -->|Yes / Cached| VariantA
     Segmented? -->|No| Rollout[Rollout Resolve]
-    Rollout --> Control
+    Rollout -->|Cached| Control
     Rollout -->|Cached| VariantA
     Rollout -->|Cached| VariantB
     Rollout -->|Cached| VariantN
 
-class ForcedVariant,VariantA,VariantB,VariantN included
-class Control,Excluded excluded
+class ForcedVariant,VariantA,VariantB,VariantN,Control included
+class Excluded excluded
 class Cached cached
 ```
 
@@ -901,6 +900,7 @@ class Cached cached
 3. Cache provides consistency across calls
 4. Segmentation takes priority over rollout
 5. `only_assigned: true` exits early if no cache hit
+6. Control is cached like any other variant, so the assignment stays stable across calls for every rollout strategy
 
 ### Experiment Context and Stickiness
 
@@ -1326,31 +1326,17 @@ documented in its implementation.
 
 **Control variant caching:**
 
-By default, the gem caches `:control` assignments alongside variant assignments. This is what
+The gem always caches `:control` assignments alongside variant assignments. This is what
 makes `only_assigned: true` lookups include bucketed control users -- without it, control
 users would appear unassigned at secondary tracking sites and would be silently excluded.
 
-```ruby
-# Disable globally (don't cache :control)
-Gitlab::Experiment.configure do |config|
-  config.cache_control = false
-end
-
-# Or override per-rollout
-class MyExperiment < ApplicationExperiment
-  default_rollout :percent, cache_control: false
-end
-```
-
-The `Random` rollout strategy intentionally opts out of caching `:control` regardless of this
-setting, because its convergence model depends on re-rolling control assignments on every
-visit until a non-control variant is picked.
+This applies to every rollout strategy.
 
-**Operational note:** With control caching enabled, `Percent` and `RoundRobin` cache hashes
-grow with every bucketed user, not just users assigned to a candidate variant. For
-long-running experiments the cache will be roughly `1 / candidate_percentage` the size it
-would have been before. Plan periodic cleanup using your store's deletion API -- for the
-`RedisHashStore`, that's `experiment.cache.store.clear(key: experiment.name)`.
+**Operational note:** Because control is cached, cache hashes grow with every bucketed
+user, not just users assigned to a candidate variant. For long-running experiments the
+cache will be roughly `1 / candidate_percentage` the size it would have been before. Plan
+periodic cleanup using your store's deletion API -- for the `RedisHashStore`, that's
+`experiment.cache.store.clear(key: experiment.name)`.
 
 ### Advanced: Custom Rollout Strategies
 

data/lib/generators/gitlab/experiment/install/templates/initializer.rb.tt

@@ -22,20 +22,6 @@ Gitlab::Experiment.configure do |config|
   # Use `nil` for no caching.
   config.cache = nil
 
-  # Cache `:control` assignments alongside variant assignments.
-  #
-  # When set to true (the default), bucketed control users are cached and
-  # therefore visible to `only_assigned: true` tracking calls. Set to false
-  # to skip caching control -- control users will be treated as unassigned
-  # at `only_assigned` sites and excluded from tracking there.
-  #
-  # Can be overridden per-rollout:
-  #
-  # class ExampleExperiment < ApplicationExperiment
-  #   default_rollout :percent, cache_control: false
-  # end
-  config.cache_control = true
-
   # The domain to use on cookies.
   #
   # When not set, it uses the current host. If you want to provide specific

data/lib/gitlab/experiment/configuration.rb

@@ -30,21 +30,6 @@ module Gitlab
       # Use `nil` for no caching.
       @cache = nil
 
-      # Whether `:control` assignments should be written to the cache.
-      #
-      # When true (default), control variants are cached alongside other
-      # variants, which is required for `only_assigned: true` tracking to
-      # work correctly for the control arm of an experiment.
-      #
-      # When false, control variants are not cached. This preserves the
-      # behavior of versions prior to this option being introduced. Any
-      # experiment using `only_assigned: true` will silently exclude
-      # control users from tracking.
-      #
-      # Individual rollouts can override this via the `cache_control:`
-      # option, e.g. `default_rollout :percent, cache_control: false`.
-      @cache_control = true
-
       # The domain to use on cookies.
       #
       # When not set, it uses the current host. If you want to provide specific
@@ -208,7 +193,6 @@ module Gitlab
           :base_class,
           :strict_registration,
           :cache,
-          :cache_control,
           :cookie_domain,
           :cookie_name,
           :secure_cookie,
@@ -229,19 +213,6 @@ module Gitlab
           @default_rollout = Rollout.resolve(*args)
         end
 
-        def cache_control=(value) # rubocop:disable Lint/DuplicateMethods
-          if value != true
-            deprecated(
-              :cache_control,
-              "setting `cache_control` to a non-true value is deprecated and will be removed in version 2.0. " \
-                "Control variants will always be cached.",
-              version: '1.4'
-            )
-          end
-
-          @cache_control = value
-        end
-
         # Internal warning helpers.
 
         def deprecated(*args, version:, stack: 0)

data/lib/gitlab/experiment/errors.rb

@@ -7,7 +7,6 @@ module Gitlab
     UnregisteredExperiment = Class.new(Error)
     ExistingBehaviorError = Class.new(Error)
     BehaviorMissingError = Class.new(Error)
-    ControlNotCachedError = Class.new(Error)
 
     class NestingError < Error
       def initialize(experiment:, nested_experiment:)

data/lib/gitlab/experiment/rollout/random.rb

@@ -1,14 +1,12 @@
 # frozen_string_literal: true
 
-# The random rollout strategy will randomly assign a variant when the context is determined to be within the experiment
-# group.
+# The random rollout strategy picks a variant uniformly at random the first time a context is assigned into the
+# experiment group.
 #
-# If caching is enabled this is a predictable and consistent assignment that will eventually assign a non-control
-# variant. This relies on the strategy intentionally NOT caching control assignments -- so when a context is sampled
-# into control, it gets re-rolled on the next visit until it lands on a non-control variant, at which point the
-# assignment is cached and stable. Without caching, assignment is random on every call.
+# If caching is enabled, that first roll is persisted and the context gets the same variant on every subsequent visit,
+# so the assignment is stable/sticky per context -- including :control, which is cached like any other variant. Without
+# caching, assignment is random on every call.
 #
-# This is the only rollout that opts out of caching control: every other rollout caches whatever variant it resolves to.
 # Example configuration usage:
 #
 # config.default_rollout = Gitlab::Experiment::Rollout::Random.new
@@ -31,10 +29,7 @@ module Gitlab
         protected
 
         def execute_assignment
-          result = behavior_names.sample # pick a random variant
-          # Drop :control so it's never cached, even if cache_control is true.
-          # The context will be re-rolled on the next visit and eventually converge on a non-control variant.
-          result == :control ? nil : result
+          behavior_names.sample # pick a random variant; cached on first roll so it stays stable
         end
       end
     end

data/lib/gitlab/experiment/rollout.rb

@@ -31,15 +31,6 @@ module Gitlab
 
           @experiment = experiment
           @options = options
-
-          return if !options.key?(:cache_control) || options[:cache_control] == true
-
-          Configuration.deprecated(
-            :cache_control,
-            "setting `cache_control` to a non-true value on a rollout is deprecated and " \
-              "will be removed in version 2.0. Control variants will always be cached.",
-            version: '1.4'
-          )
         end
 
         def enabled?
@@ -49,18 +40,9 @@ module Gitlab
         def resolve
           validate! # allow the rollout strategy to validate itself
 
-          assignment = execute_assignment
-          # Cache control assignments unless explicitly opted out. The per-rollout `cache_control:`
-          # option takes precedence over the global `Configuration.cache_control` default.
-          return assignment if cache_control_enabled?
-
-          assignment == :control ? nil : assignment
-        end
-
-        # Returns true when this rollout caches `:control` assignments. Per-rollout
-        # `cache_control:` option takes precedence over the global default.
-        def cache_control_enabled?
-          options.fetch(:cache_control, Configuration.cache_control)
+          # Control variants are cached alongside other variants, which is required
+          # for `only_assigned: true` tracking to work for the control arm.
+          execute_assignment
         end
 
         private

data/lib/gitlab/experiment/version.rb

@@ -2,6 +2,6 @@
 
 module Gitlab
   class Experiment
-    VERSION = '1.6.0'
+    VERSION = '2.0.0'
   end
 end

data/lib/gitlab/experiment.rb

@@ -168,13 +168,6 @@ module Gitlab
     def only_assigned?
       return false unless context.only_assigned
 
-      unless rollout.cache_control_enabled?
-        raise ControlNotCachedError,
-          "`only_assigned: true` requires `cache_control: true`, but the rollout for " \
-            "experiment `#{name}` has it disabled. Control users would be silently excluded " \
-            "from tracking. Enable cache_control or remove `only_assigned: true`."
-      end
-
       find_variant.blank?
     end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gitlab-experiment
 version: !ruby/object:Gem::Version
-  version: 1.6.0
+  version: 2.0.0
 platform: ruby
 authors:
 - GitLab
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-23 00:00:00.000000000 Z
+date: 2026-07-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport