gitlab-experiment 0.9.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2ff3ecacc0f83a605ecaad79cef7368802307b9bc1c106eca1c74967ade3a00c
-  data.tar.gz: a72ceadbbcd689a290bdf7f85b9dababa7f7ae252bc3886a6fcd42170e561ee7
+  metadata.gz: 45c95c2d6d85df98de92096ab00a7cb124ef3cf46f2dfa858465b3c43df8b22d
+  data.tar.gz: 17716054da0e7aff4c67ddea28c733ec275eaf95934d627bbea40856427ecb68
 SHA512:
-  metadata.gz: 6d7f1804cf3503fd0fcf5be75ca6c4d3bfebcdccd3baf5aa3937a7c080e8336c15491a3476a9a7aef30060d0a526f4f71c6803d0a8ae8c08b0192e1401e1070c
-  data.tar.gz: 4f739b5852733e789ab23ce0b96215d023e4483ef32ae055373bfe3083d212fb5f01aa8b45ee55bfbac0a8a734e5ec429eac175a49a0219256d6f8f62151027a
+  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
@@ -514,7 +581,7 @@ class PillColorExperiment < Gitlab::Experiment # OR ApplicationExperiment
 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
@@ -601,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. 
@@ -616,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) }
@@ -685,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/gitlab/experiment/cache.rb

@@ -46,20 +46,24 @@ 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|
           value = store.read(old_key)
@@ -69,7 +73,7 @@ module Gitlab
           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/context.rb

@@ -5,9 +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
+      attr_reader :request, :only_assigned
 
       def initialize(experiment, **initial_value)
         @experiment = experiment
@@ -26,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))
 

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

@@ -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
@@ -72,6 +73,10 @@ module Gitlab
             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'

data/lib/gitlab/experiment/version.rb

@@ -2,6 +2,6 @@
 
 module Gitlab
   class Experiment
-    VERSION = '0.9.1'
+    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.9.1
+  version: 1.0.0
 platform: ruby
 authors:
 - GitLab
 autorequire:
 bindir: bin
 cert_chain: []
-date:
+date: 2025-09-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -58,14 +58,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 10.1.0
+        version: 12.0.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 10.1.0
+        version: 12.0.1
 - !ruby/object:Gem::Dependency
   name: lefthook
   requirement: !ruby/object:Gem::Requirement
@@ -100,28 +100,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.20.2
+        version: 2.24.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.20.2
+        version: 2.24.0
 - !ruby/object:Gem::Dependency
   name: rubocop-rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.22.0
+        version: 2.27.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.22.0
+        version: 2.27.1
 - !ruby/object:Gem::Dependency
   name: flipper
   requirement: !ruby/object:Gem::Requirement
@@ -184,14 +184,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.1.0
+        version: 3.1.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.1.0
+        version: 3.1.0
 description:
 email:
 - gitlab_rubygems@gitlab.com
@@ -199,33 +199,23 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- lib/generators/gitlab
-- lib/generators/gitlab/experiment
+- LICENSE.txt
+- README.md
 - lib/generators/gitlab/experiment/USAGE
 - lib/generators/gitlab/experiment/experiment_generator.rb
-- lib/generators/gitlab/experiment/install
 - lib/generators/gitlab/experiment/install/install_generator.rb
-- lib/generators/gitlab/experiment/install/templates
 - lib/generators/gitlab/experiment/install/templates/POST_INSTALL
 - lib/generators/gitlab/experiment/install/templates/application_experiment.rb.tt
 - lib/generators/gitlab/experiment/install/templates/initializer.rb.tt
-- lib/generators/gitlab/experiment/templates
 - lib/generators/gitlab/experiment/templates/experiment.rb.tt
-- lib/generators/rspec
-- lib/generators/rspec/experiment
 - lib/generators/rspec/experiment/experiment_generator.rb
-- lib/generators/rspec/experiment/templates
 - lib/generators/rspec/experiment/templates/experiment_spec.rb.tt
-- lib/generators/test_unit
-- lib/generators/test_unit/experiment
 - lib/generators/test_unit/experiment/experiment_generator.rb
-- lib/generators/test_unit/experiment/templates
 - lib/generators/test_unit/experiment/templates/experiment_test.rb.tt
-- lib/gitlab/experiment
+- lib/gitlab/experiment.rb
 - lib/gitlab/experiment/base_interface.rb
-- lib/gitlab/experiment/cache
-- lib/gitlab/experiment/cache/redis_hash_store.rb
 - lib/gitlab/experiment/cache.rb
+- lib/gitlab/experiment/cache/redis_hash_store.rb
 - lib/gitlab/experiment/callbacks.rb
 - lib/gitlab/experiment/configuration.rb
 - lib/gitlab/experiment/context.rb
@@ -235,19 +225,14 @@ files:
 - lib/gitlab/experiment/errors.rb
 - lib/gitlab/experiment/middleware.rb
 - lib/gitlab/experiment/nestable.rb
-- lib/gitlab/experiment/rollout
+- lib/gitlab/experiment/rollout.rb
 - lib/gitlab/experiment/rollout/percent.rb
 - lib/gitlab/experiment/rollout/random.rb
 - lib/gitlab/experiment/rollout/round_robin.rb
-- lib/gitlab/experiment/rollout.rb
 - lib/gitlab/experiment/rspec.rb
-- lib/gitlab/experiment/test_behaviors
 - lib/gitlab/experiment/test_behaviors/trackable.rb
 - lib/gitlab/experiment/variant.rb
 - lib/gitlab/experiment/version.rb
-- lib/gitlab/experiment.rb
-- LICENSE.txt
-- README.md
 homepage: https://gitlab.com/gitlab-org/ruby/gems/gitlab-experiment
 licenses:
 - MIT
@@ -260,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.3.26
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: GitLab experimentation library.