gitlab-experiment 0.9.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2ff3ecacc0f83a605ecaad79cef7368802307b9bc1c106eca1c74967ade3a00c
-  data.tar.gz: a72ceadbbcd689a290bdf7f85b9dababa7f7ae252bc3886a6fcd42170e561ee7
+  metadata.gz: 3305c24f350ec02a3ef81da742a6d108c7aef00623f8b2534f989f06ec4a2ba6
+  data.tar.gz: 5f9113235e1623a2012ea5e4c451ed41baeb847e5883951b95b44fd6d7fd40fa
 SHA512:
-  metadata.gz: 6d7f1804cf3503fd0fcf5be75ca6c4d3bfebcdccd3baf5aa3937a7c080e8336c15491a3476a9a7aef30060d0a526f4f71c6803d0a8ae8c08b0192e1401e1070c
-  data.tar.gz: 4f739b5852733e789ab23ce0b96215d023e4483ef32ae055373bfe3083d212fb5f01aa8b45ee55bfbac0a8a734e5ec429eac175a49a0219256d6f8f62151027a
+  metadata.gz: d7120d36eb59039dbe36eb728990b951b96b7aa118a0a73af32e18809eaed265d03dec4689b55c3118e14a252418c9c84c4e25f7c25573205c6ef5269e5f456f
+  data.tar.gz: 9233969833c74c432b187721a2b35a38e521fce3679bccf64f879b87c899e6202b0f60b047c5aa57aef10665816f3fd7b3d21f7e403b30424b1227017c9991b2

data/README.md

@@ -195,7 +195,9 @@ experiment(:pill_color, actor: User.first).run # => "red"
 
 ### Exclusion rules
 
-Exclusion rules let us determine if a context should even be considered as something to include in an experiment. If we're excluding something, it means that we don't want to run the experiment in that case. This can be useful if you only want to run experiments on new users for instance.
+Exclusion rules let us determine if a context should even be considered as something to include in an experiment. If
+we're excluding something, it means that we don't want to run the experiment in that case. This can be useful if you
+only want to run experiments on new users for instance.
 
 ```ruby
 class PillColorExperiment < Gitlab::Experiment # OR ApplicationExperiment
@@ -205,15 +207,40 @@ class PillColorExperiment < Gitlab::Experiment # OR ApplicationExperiment
 end
 ```
 
-In the previous example, we'll exclude all users named `'Richard'` as well as any account older than 2 weeks old. Not only will they be immediately given the control behavior, but no events will be tracked in these cases either.
+In the previous example, we'll exclude all users named `'Richard'` as well as any account older than 2 weeks old. Not
+only will they be immediately given the control behavior, but no events will be tracked in these cases either.
 
-Exclusion rules are executed in the order they're defined. The first exclusion rule to produce a truthy result will halt execution of further exclusion checks.
+Exclusion rules are executed in the order they're defined. The first exclusion rule to produce a truthy result will halt
+execution of further exclusion checks.
 
-Note: Although tracking calls will be ignored on all exclusions, you may want to check exclusion yourself in expensive custom logic by calling the `should_track?` or `excluded?` methods.
+#### Excluding from within the experiment block
 
-Note: When using exclusion rules it's important to understand that the control assignment is cached, which improves future experiment run performance but can be a gotcha around caching.
+You can also exclude contexts dynamically from within the experiment block using the `exclude!` method. This provides a
+convenient way to include exclusion logic directly within the experiment call:
 
-Note: Exclusion rules aren't the best way to determine if an experiment is enabled. There's an `enabled?` method that can be overridden to have a high-level way of determining if an experiment should be running and tracking at all. This `enabled?` check should be as efficient as possible because it's the first early opt out path an experiment can implement. This can be seen in [How it works](#how-it-works).
+```ruby
+experiment(:pill_color, actor: current_user) do |e|
+  e.exclude! unless can?(current_user, :manage, project)
+
+  e.control { 'blue' }
+  e.candidate { 'red' }
+end
+```
+
+This approach keeps the experiment logic wrapped nicely within the experiment block, rather than requiring you to wrap
+the entire experiment call in conditional logic. When `exclude!` is called, the experiment will be excluded and return
+the control behavior without tracking any events.
+
+Note: Although tracking calls will be ignored on all exclusions, you may want to check exclusion yourself in expensive
+custom logic by calling the `should_track?` or `excluded?` methods.
+
+Note: When using exclusion rules it's important to understand that the control assignment is cached, which improves
+future experiment run performance but can be a gotcha around caching.
+
+Note: Exclusion rules aren't the best way to determine if an experiment is enabled. There's an `enabled?` method that
+can be overridden to have a high-level way of determining if an experiment should be running and tracking at all. This
+`enabled?` check should be as efficient as possible because it's the first early opt out path an experiment can
+implement. This can be seen in [How it works](#how-it-works).
 
 ### Segmentation rules
 
@@ -258,6 +285,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 +368,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 +391,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 +608,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 +695,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 +734,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) }
@@ -679,12 +797,21 @@ Each of these approaches could be desirable given the objectives of your experim
 
 After cloning the repo, run `bundle install` to install dependencies.
 
-Run `bundle exec rake` to run the tests. You can also run `bundle exec pry` for an interactive prompt that will allow you to experiment.
+## Running tests
+
+The test suite requires Redis to be running. [Install](https://redis.io/docs/latest/operate/oss_and_stack/install/archive/install-redis/) and start Redis (`redis-server`) before running tests. 
+
+Once Redis is running, execute the tests:
+`bundle exec rake`
+
+You can also run `bundle exec pry` for an interactive prompt that will allow you to experiment.
 
 ## Contributing
 
 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/install/templates/initializer.rb.tt

@@ -31,6 +31,14 @@ Gitlab::Experiment.configure do |config|
   #   nil, :all, or ['www.gitlab.com', '.gitlab.com']
   config.cookie_domain = :all
 
+  # Mark experiment cookies as secure (HTTPS only).
+  #
+  # When set to true, cookies will have the secure flag set, meaning they
+  # will only be sent over HTTPS connections. Defaults to true.
+  #
+  # Set to false in development/test environments if needed:
+  #   config.secure_cookie = Rails.env.production?
+
   # The default rollout strategy.
   #
   # The recommended default rollout strategy when not using caching would

data/lib/generators/rspec/experiment/templates/experiment_spec.rb.tt

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'rails_helper'
+require 'spec_helper'
 
 <% module_namespacing do -%>
 RSpec.describe <%= class_name %>Experiment do

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/configuration.rb

@@ -44,6 +44,15 @@ module Gitlab
         "#{experiment.name}_id"
       end
 
+      # Mark experiment cookies as secure (HTTPS only).
+      #
+      # When set to true, cookies will have the secure flag set, meaning they
+      # will only be sent over HTTPS connections. Defaults to true.
+      #
+      # Set to false in development/test environments if needed:
+      #   config.secure_cookie = Rails.env.production?
+      @secure_cookie = true
+
       # The default rollout strategy.
       #
       # The recommended default rollout strategy when not using caching would
@@ -177,6 +186,7 @@ module Gitlab
           :cache,
           :cookie_domain,
           :cookie_name,
+          :secure_cookie,
           :context_key_secret,
           :context_key_bit_length,
           :mount_at,

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/cookies.rb

@@ -32,7 +32,7 @@ module Gitlab
 
         cookie ||= SecureRandom.uuid
         cookie_jar.permanent.signed[cookie_name] = {
-          value: cookie, secure: true, domain: domain, httponly: true
+          value: cookie, secure: Configuration.secure_cookie, domain: domain, httponly: true
         }
 
         hash.merge(key => cookie)

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.1.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.1.0
 platform: ruby
 authors:
 - GitLab
 autorequire:
 bindir: bin
 cert_chain: []
-date:
+date: 2025-11-27 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.