gitlab-experiment 0.8.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c92b7e2d77e534a23b8233f11539fa9c2767b21adab9c247e916933724dd7f5d
-  data.tar.gz: 7a1144676a16835f64eaefb9ea7bac2b7055c5cf8e329d55dba6c115be17eb50
+  metadata.gz: 45c95c2d6d85df98de92096ab00a7cb124ef3cf46f2dfa858465b3c43df8b22d
+  data.tar.gz: 17716054da0e7aff4c67ddea28c733ec275eaf95934d627bbea40856427ecb68
 SHA512:
-  metadata.gz: b7a645b7d2c3cf13d7031fc61dfdaef2626d0092661093a19ff5e21d346adda8cbe031b5c360de21fda3ecee828eaa7bda0a6afe839b6c5ce7ba57f9e10232eb
-  data.tar.gz: 1a8e4672a903746f5f31f2cf5dcf815bb6e2c3cb8c8fa73430c93462977310fcd6ed2f6f8676d5e2ccf856289c6befde6469e9f29715341c4bde7fd0b14fa51b
+  metadata.gz: a3549e9ec7f899a6994937545c1afcfaceac52efa373b3e7e594b4cd1a08e7df376d1bf79403704d681ea48a29362358ff36fd5cb0fdff6fca29c79c097c0fbb
+  data.tar.gz: 7da4141f53babfa226082190ef4c144900df52a8c1c35d03b1270dd4f3f8c2c1be16aad59a9d2da1e833d0a063177b4212744aad9e6a273637c265ea2148d317

data/README.md

@@ -258,6 +258,73 @@ class PillColorExperiment < Gitlab::Experiment # OR ApplicationExperiment
 end
 ```
 
+### Checking assignment without assigning
+
+Sometimes you may want to check if a user is already assigned to an experiment without assigning them to a variant if
+they're not. This is useful when you want to show experiment-specific content only to users who are already
+participating in the experiment, without expanding the experiment's reach.
+
+You can use the `only_assigned` option to achieve this behavior:
+
+```haml
+-# Only show experimental features to users already participating in the experiment
+- experiment(:advanced_search, actor: current_user, only_assigned: true) do |e|
+  - e.control do
+    = render 'search_filters'
+  - e.candidate do
+    = render 'advanced_search_filters'
+```
+
+When `only_assigned: true` is used:
+
+- If the user has a cached variant assignment, the experiment runs normally and returns that variant
+- If the user has no cached variant assignment, the experiment is excluded and returns the control behavior
+- No new variant assignments are made
+- Tracking is disabled for excluded cases
+- Publishing still works to record the exclusion
+
+This is particularly useful for:
+
+- **Progressive rollouts**: Show experimental features only to users already in the experiment
+- **Conditional UI**: Display experiment-specific UI elements only for assigned users
+- **Feature gates**: Check experiment participation without expanding the participant pool
+- **Cleanup phases**: Maintain experience for existing participants while preventing new assignments
+- **Post-registration experiences**: When users are assigned to experiments during registration, you can later show
+  experimental features throughout their journey without expanding to existing users who weren't initially assigned
+
+```ruby
+# During user registration - assign new users to experiment variants
+class RegistrationsController < ApplicationController
+  def create
+    # ... user creation logic
+    
+    # Assign new users to the experiment
+    experiment(:pill_color, actor: @user)
+  end
+end
+```
+
+```haml
+-# Later throughout the app - only show experimental features to assigned users
+- experiment(:pill_color, actor: current_user, only_assigned: true) do |e|
+  - e.control do
+  - e.candidate do
+    = render 'quick_start_guide'
+```
+
+You can also assign the result of the experiment to a variable:
+
+```ruby
+# In a view helper or directly in the view
+button_class = experiment(:pill_color, actor: current_user, only_assigned: true) do |e|
+  e.control { 'btn-default' }
+  e.candidate { 'btn-primary' }
+end.run
+```
+
+Note: The `only_assigned` option requires caching to be enabled in your experiment configuration, as it relies on
+checking for cached variant assignments.
+
 ### Rollout strategies
 
 While a default rollout strategy can be defined in configuration, it's useful to be able to override this per experiment if needed. You can do this by specifying a specific `default_rollout` override in your experiment class.
@@ -274,7 +341,12 @@ Obviously random assignment might not be the best rollout strategy for you, but
 
 ## How it works
 
-The way experiments work is best described using the following decision tree diagram. When an experiment is run, the following logic is executed to resolve what experience should be provided, given how the experiment is defined, and using the context passed to the experiment call.
+The way experiments work is best described using the following decision tree diagram. When an experiment is run, the
+following logic is executed to resolve what experience should be provided, given how the experiment is defined, and
+using the context passed to the experiment call.
+
+Note: When using the `only_assigned` option, experiments that have no cached variant will be excluded, preventing new
+variant assignments while maintaining existing ones.
 
 ```mermaid
 graph TD
@@ -292,11 +364,6 @@ graph TD
     Rollout -->|Cached| VariantB
     Rollout -->|Cached| VariantN
 
-classDef included fill:#380d75,color:#ffffff,stroke:none
-classDef excluded fill:#fca121,stroke:none
-classDef cached fill:#2e2e2e,color:#ffffff,stroke:none
-classDef default fill:#fff,stroke:#6e49cb
-
 class VariantA,VariantB,VariantN included
 class Control,Excluded excluded
 class Cached cached
@@ -499,9 +566,7 @@ Anyway, now you can use your custom `Flipper` rollout strategy by instantiating
 
 ```ruby
 Gitlab::Experiment.configure do |config|
-  config.default_rollout = Gitlab::Experiment::Rollout::Flipper.new(
-    include_control: true # specify to include control, which we want to do
-  )
+  config.default_rollout = Gitlab::Experiment::Rollout::Flipper.new
 end
 ```
 
@@ -512,12 +577,11 @@ class PillColorExperiment < Gitlab::Experiment # OR ApplicationExperiment
   # ...registered behaviors
 
   default_rollout :flipper,
-    include_control: true, # optionally specify to include control
     distribution: { control: 26, red: 37, blue: 37 } # optionally specify distribution
 end
 ```
 
-Now, enabling or disabling the Flipper feature flag will control if the experiment is enabled or not. If the experiment is enabled, as determined by our custom rollout strategy, the standard resolutuon logic will be executed, and a variant (or control) will be assigned.
+Now, enabling or disabling the Flipper feature flag will control if the experiment is enabled or not. If the experiment is enabled, as determined by our custom rollout strategy, the standard resolution logic will be executed, and a variant (or control) will be assigned.
 
 ```ruby
 experiment(:pill_color).enabled? # => false
@@ -604,6 +668,30 @@ it "stubs experiments while allowing the rollout strategy to assign the variant"
 end
 ```
 
+You can also test the `only_assigned` behavior by stubbing cache states:
+
+```ruby
+it "tests only_assigned behavior with cached variants" do
+  # Stub a cached variant to exist
+  allow_any_instance_of(Gitlab::Experiment).to receive(:find_variant).and_return('red')
+  
+  experiment_instance = experiment(:pill_color, actor: user, only_assigned: true)
+  
+  expect(experiment_instance).not_to be_excluded
+  expect(experiment_instance.run).to eq('red')
+end
+
+it "tests only_assigned behavior without cached variants" do
+  # Stub no cached variant
+  allow_any_instance_of(Gitlab::Experiment).to receive(:find_variant).and_return(nil)
+  
+  experiment_instance = experiment(:pill_color, actor: user, only_assigned: true)
+  
+  expect(experiment_instance).to be_excluded
+  expect(experiment_instance.run).to eq('blue') # control behavior
+end
+```
+
 ### Registered behaviors matcher
 
 It's useful to test our registered behaviors, as well as their return values when we implement anything complex in them. The `register_behavior` matcher is useful for this. 
@@ -619,7 +707,7 @@ end
 
 ### Exclusion and segmentation matchers
 
-You can also easily test your experiment classes using the `exclude`, `segment` metchers.
+You can also easily test your experiment classes using the `exclude`, `segment` matchers.
 
 ```ruby
 let(:excluded) { double(first_name: 'Richard', created_at: Time.current) }
@@ -688,6 +776,8 @@ Run `bundle exec rake` to run the tests. You can also run `bundle exec pry` for
 
 Bug reports and merge requests are welcome on GitLab at https://gitlab.com/gitlab-org/ruby/gems/gitlab-experiment. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
+Make sure to include a changelog entry in your commit message and read the [changelog entries section](https://docs.gitlab.com/ee/development/changelog.html).
+
 ## Release process
 
 Please refer to the [Release Process](docs/release_process.md).

data/lib/generators/gitlab/experiment/experiment_generator.rb

@@ -8,15 +8,9 @@ module Gitlab
       source_root File.expand_path('templates/', __dir__)
       check_class_collision suffix: 'Experiment'
 
-      argument     :variants,
-                   type: :array,
-                   default: %w[control candidate],
-                   banner: 'variant variant'
-
-      class_option :skip_comments,
-                   type: :boolean,
-                   default: false,
-                   desc: 'Omit helpful comments from generated files'
+      argument :variants, type: :array, default: %w[control candidate], banner: 'variant variant'
+
+      class_option :skip_comments, type: :boolean, default: false, desc: 'Omit helpful comments from generated files'
 
       def create_experiment
         template 'experiment.rb', File.join('app/experiments', class_path, "#{file_name}_experiment.rb")

data/lib/generators/gitlab/experiment/install/install_generator.rb

@@ -11,14 +11,9 @@ module Gitlab
         desc 'Installs the Gitlab::Experiment initializer and optional ApplicationExperiment into your application.'
 
         class_option :skip_initializer,
-                     type: :boolean,
-                     default: false,
-                     desc: 'Skip the initializer with default configuration'
-
-        class_option :skip_baseclass,
-                     type: :boolean,
-                     default: false,
-                     desc: 'Skip the ApplicationExperiment base class'
+          type: :boolean, default: false, desc: 'Skip the initializer with default configuration'
+
+        class_option :skip_baseclass, type: :boolean, default: false, desc: 'Skip the ApplicationExperiment base class'
 
         def create_initializer
           return if options[:skip_initializer]

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

@@ -43,15 +43,12 @@ Gitlab::Experiment.configure do |config|
   # Each experiment can specify its own rollout strategy:
   #
   # class ExampleExperiment < ApplicationExperiment
-  #   default_rollout :random,              # :percent, :round_robin,
-  #                   include_control: true # or MyCustomRollout
+  #   default_rollout :random # :percent, :round_robin, or MyCustomRollout
   # end
   #
   # Included rollout strategies:
   #   :percent (recommended), :round_robin, or :random
-  config.default_rollout = :percent, {
-    include_control: true # include control in possible assignments
-  }
+  config.default_rollout = :percent
 
   # Secret seed used in generating context keys.
   #

data/lib/gitlab/experiment/cache/redis_hash_store.rb

@@ -48,18 +48,18 @@ module Gitlab
           key.to_s.split(':') # this assumes the default strategy in gitlab-experiment
         end
 
-        def read_entry(key, **options)
+        def read_entry(key, **_options)
           value = pool { |redis| redis.hget(*hkey(key)) }
           value.nil? ? nil : ActiveSupport::Cache::Entry.new(value)
         end
 
-        def write_entry(key, entry, **options)
+        def write_entry(key, entry, **_options)
           return false if entry.value.blank? # don't cache any empty values
 
           pool { |redis| redis.hset(*hkey(key), entry.value) }
         end
 
-        def delete_entry(key, **options)
+        def delete_entry(key, **_options)
           pool { |redis| redis.hdel(*hkey(key)) }
         end
       end

data/lib/gitlab/experiment/cache.rb

@@ -46,28 +46,34 @@ module Gitlab
       def cache_variant(specified = nil, &block)
         return (specified.presence || yield) unless cache.store
 
-        result = migrated_cache_fetch(cache.store, &block)
+        result = migrated_cache_fetch(cache.store) || find_variant(&block)
         return result unless specified.present?
 
         cache.write(specified) if result.to_s != specified.to_s
         specified
       end
 
+      def find_variant(&block)
+        cache.store.fetch(cache_key, &block)
+      end
+
       def cache_key(key = nil, suffix: nil)
         "#{[name, suffix].compact.join('_')}:#{key || context.signature[:key]}"
       end
 
       private
 
-      def migrated_cache_fetch(store, &block)
+      def migrated_cache_fetch(store)
         migrations = context.signature[:migration_keys]&.map { |key| cache_key(key) } || []
         migrations.find do |old_key|
-          next unless (value = store.read(old_key))
+          value = store.read(old_key)
+
+          next unless value
 
           store.write(cache_key, value)
           store.delete(old_key)
           break value
-        end || store.fetch(cache_key, &block)
+        end
       end
     end
   end

data/lib/gitlab/experiment/configuration.rb

@@ -39,6 +39,11 @@ module Gitlab
       #   nil, :all, or ['www.gitlab.com', '.gitlab.com']
       @cookie_domain = :all
 
+      # The cookie name for an experiment.
+      @cookie_name = lambda do |experiment|
+        "#{experiment.name}_id"
+      end
+
       # The default rollout strategy.
       #
       # The recommended default rollout strategy when not using caching would
@@ -51,8 +56,7 @@ module Gitlab
       # Each experiment can specify its own rollout strategy:
       #
       # class ExampleExperiment < ApplicationExperiment
-      #   default_rollout :random,              # :percent, :round_robin,
-      #                   include_control: true # or MyCustomRollout
+      #   default_rollout :random # :percent, :round_robin, or MyCustomRollout
       # end
       #
       # Included rollout strategies:
@@ -172,6 +176,7 @@ module Gitlab
           :strict_registration,
           :cache,
           :cookie_domain,
+          :cookie_name,
           :context_key_secret,
           :context_key_bit_length,
           :mount_at,

data/lib/gitlab/experiment/context.rb

@@ -5,7 +5,9 @@ module Gitlab
     class Context
       include Cookies
 
-      DNT_REGEXP = /^(true|t|yes|y|1|on)$/i.freeze
+      DNT_REGEXP = /^(true|t|yes|y|1|on)$/i
+
+      attr_reader :request, :only_assigned
 
       def initialize(experiment, **initial_value)
         @experiment = experiment
@@ -24,6 +26,7 @@ module Gitlab
         return @value if value.nil?
 
         value = value.dup # dup so we don't mutate
+        @only_assigned = value.delete(:only_assigned)
         reinitialize(value.delete(:request))
         key(value.delete(:sticky_to))
 
@@ -63,7 +66,7 @@ module Gitlab
         add_unmerged_migration(value.delete(:migrated_from))
         add_merged_migration(value.delete(:migrated_with))
 
-        migrate_cookie(value, "#{@experiment.name}_id")
+        migrate_cookie(value, @experiment.instance_exec(@experiment, &Configuration.cookie_name))
       end
 
       def add_unmerged_migration(value = {})

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

@@ -34,10 +34,10 @@ module Gitlab
         def validate!
           case distribution_rules
           when nil then nil
-          when Array, Hash
-            if distribution_rules.length != behavior_names.length
-              raise InvalidRolloutRules, "the distribution rules don't match the number of behaviors defined"
-            end
+          when Array
+            validate_distribution_rules(distribution_rules)
+          when Hash
+            validate_distribution_rules(distribution_rules.values)
           else
             raise InvalidRolloutRules, 'unknown distribution options type'
           end
@@ -49,9 +49,10 @@ module Gitlab
 
           case distribution_rules
           when Array # run through the rules until finding an acceptable one
-            behavior_names[distribution_rules.find_index { |percent| crc % 100 <= total += percent }]
+            index = distribution_rules.find_index { |percent| crc % 100 < total += percent unless percent == 0 }
+            behavior_names[index]
           when Hash # run through the variant names until finding an acceptable one
-            distribution_rules.find { |_, percent| crc % 100 <= total += percent }.first
+            distribution_rules.find { |_, percent| crc % 100 < total += percent unless percent == 0 }.first
           else # assume even distribution on no rules
             behavior_names.empty? ? nil : behavior_names[crc % behavior_names.length]
           end
@@ -66,6 +67,20 @@ module Gitlab
         def distribution_rules
           options[:distribution]
         end
+
+        def validate_distribution_rules(distributions)
+          if distributions.length != behavior_names.length
+            raise InvalidRolloutRules, "the distribution rules don't match the number of behaviors defined"
+          end
+
+          if distributions.any? { |percent| percent < 0 }
+            raise InvalidRolloutRules, "the distribution percentage cannot be negative"
+          end
+
+          return if distributions.sum == 100
+
+          raise InvalidRolloutRules, 'the distribution percentages should add up to 100'
+        end
       end
     end
   end

data/lib/gitlab/experiment/version.rb

@@ -2,6 +2,6 @@
 
 module Gitlab
   class Experiment
-    VERSION = '0.8.0'
+    VERSION = '1.0.0'
   end
 end

data/lib/gitlab/experiment.rb

@@ -158,7 +158,11 @@ module Gitlab
     def excluded?
       return @_excluded if defined?(@_excluded)
 
-      @_excluded = !run_callbacks(exclusion_callback_chain) { :not_excluded }
+      @_excluded = !run_callbacks(exclusion_callback_chain) { :not_excluded } || only_assigned?
+    end
+
+    def only_assigned?
+      !!context.only_assigned && find_variant.blank?
     end
 
     def should_track?

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gitlab-experiment
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 1.0.0
 platform: ruby
 authors:
 - GitLab
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-03-07 00:00:00.000000000 Z
+date: 2025-09-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -38,6 +38,160 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: gitlab-dangerfiles
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 4.1.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 4.1.0
+- !ruby/object:Gem::Dependency
+  name: gitlab-styles
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 12.0.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 12.0.1
+- !ruby/object:Gem::Dependency
+  name: lefthook
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.4.7
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.4.7
+- !ruby/object:Gem::Dependency
+  name: pry-byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.10.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.10.1
+- !ruby/object:Gem::Dependency
+  name: rubocop-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.24.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.24.0
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.27.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.27.1
+- !ruby/object:Gem::Dependency
+  name: flipper
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.26.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.26.2
+- !ruby/object:Gem::Dependency
+  name: generator_spec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.4
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.4
+- !ruby/object:Gem::Dependency
+  name: rspec-parameterized-table_syntax
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 6.0.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 6.0.3
+- !ruby/object:Gem::Dependency
+  name: simplecov-cobertura
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.1.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.1.0
 description:
 email:
 - gitlab_rubygems@gitlab.com
@@ -91,14 +245,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.6'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.7
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: GitLab experimentation library.