gitlab-experiment 0.6.2 → 0.7.0

data/lib/gitlab/experiment.rb

@@ -1,12 +1,7 @@
 # frozen_string_literal: true
 
-require 'scientist'
 require 'request_store'
-require 'active_support/callbacks'
-require 'active_support/cache'
-require 'active_support/concern'
-require 'active_support/core_ext/object/blank'
-require 'active_support/core_ext/string/inflections'
+require 'active_support'
 require 'active_support/core_ext/module/delegation'
 
 require 'gitlab/experiment/errors'
@@ -19,6 +14,7 @@ require 'gitlab/experiment/cookies'
 require 'gitlab/experiment/context'
 require 'gitlab/experiment/dsl'
 require 'gitlab/experiment/middleware'
+require 'gitlab/experiment/nestable'
 require 'gitlab/experiment/variant'
 require 'gitlab/experiment/version'
 require 'gitlab/experiment/engine' if defined?(Rails::Engine)
@@ -28,87 +24,141 @@ module Gitlab
     include BaseInterface
     include Cache
     include Callbacks
+    include Nestable
 
     class << self
-      def default_rollout(rollout = nil, options = {})
-        return @rollout ||= Configuration.default_rollout if rollout.blank?
+      # Class level behavior registration methods.
+
+      def control(*filter_list, **options, &block)
+        variant(:control, *filter_list, **options, &block)
+      end
+
+      def candidate(*filter_list, **options, &block)
+        variant(:candidate, *filter_list, **options, &block)
+      end
 
-        @rollout = Rollout.resolve(rollout).new(options)
+      def variant(variant, *filter_list, **options, &block)
+        build_behavior_callback(filter_list, variant, **options, &block)
       end
 
+      # Class level callback registration methods.
+
       def exclude(*filter_list, **options, &block)
-        build_callback(:exclusion_check, filter_list.unshift(block), **options) do |target, callback|
-          throw(:abort) if target.instance_variable_get(:@excluded) || callback.call(target, nil) == true
-        end
+        build_exclude_callback(filter_list.unshift(block), **options)
       end
 
       def segment(*filter_list, variant:, **options, &block)
-        build_callback(:segmentation_check, filter_list.unshift(block), **options) do |target, callback|
-          target.variant(variant) if target.instance_variable_get(:@variant_name).nil? && callback.call(target, nil)
-        end
+        build_segment_callback(filter_list.unshift(block), variant, **options)
+      end
+
+      def before_run(*filter_list, **options, &block)
+        build_run_callback(filter_list.unshift(:before, block), **options)
+      end
+
+      def around_run(*filter_list, **options, &block)
+        build_run_callback(filter_list.unshift(:around, block), **options)
+      end
+
+      def after_run(*filter_list, **options, &block)
+        build_run_callback(filter_list.unshift(:after, block), **options)
       end
 
+      # Class level definition methods.
+
+      def default_rollout(rollout = nil, options = {})
+        return @_rollout ||= Configuration.default_rollout if rollout.blank?
+
+        @_rollout = Rollout.resolve(rollout).new(options)
+      end
+
+      # Class level accessor methods.
+
       def published_experiments
         RequestStore.store[:published_gitlab_experiments] || {}
       end
     end
 
     def name
-      [Configuration.name_prefix, @name].compact.join('_')
+      [Configuration.name_prefix, @_name].compact.join('_')
     end
 
     def control(&block)
-      candidate(:control, &block)
+      variant(:control, &block)
     end
-    alias_method :use, :control
 
     def candidate(name = nil, &block)
-      name = (name || :candidate).to_s
-      behaviors[name] = block
+      if name.present?
+        Configuration.deprecated(<<~MESSAGE, version: '0.7.0')
+          passing name to `candidate` is deprecated and will be removed from {{release}} (instead use `variant(#{name.inspect})`)
+        MESSAGE
+      end
+
+      variant(name || :candidate, &block)
+    end
+
+    def variant(name = nil, &block)
+      if block.present? # we know we're defining a variant block
+        raise ArgumentError, 'missing variant name' if name.blank?
+
+        return behaviors[name.to_s] = block
+      end
+
+      if name.present?
+        Configuration.deprecated(<<~MESSAGE, version: '0.7.0')
+          setting the variant using `variant` is deprecated and will be removed from {{release}} (instead use `assigned(#{name.inspect})`)
+        MESSAGE
+      else
+        Configuration.deprecated(<<~MESSAGE, version: '0.7.0')
+          getting the assigned variant using `variant` is deprecated and will be removed from {{release}} (instead use `assigned`)
+        MESSAGE
+      end
+
+      assigned(name)
     end
-    alias_method :try, :candidate
 
     def context(value = nil)
-      return @context if value.blank?
+      return @_context if value.blank?
 
-      @context.value(value)
-      @context
+      @_context.value(value)
+      @_context
     end
 
-    def variant(value = nil)
-      @variant_name = cache_variant(value) if value.present?
-      return Variant.new(name: (@variant_name || :unresolved).to_s) if @variant_name || @resolving_variant
+    def assigned(value = nil)
+      @_assigned_variant_name = cache_variant(value) if value.present?
+      if @_assigned_variant_name || @_resolving_variant
+        return Variant.new(name: (@_assigned_variant_name || :unresolved).to_s)
+      end
 
       if enabled?
-        @resolving_variant = true
-        @variant_name = cached_variant_resolver(@variant_name)
+        @_resolving_variant = true
+        @_assigned_variant_name = cached_variant_resolver(@_assigned_variant_name)
       end
 
       run_callbacks(segmentation_callback_chain) do
-        @variant_name ||= :control
-        Variant.new(name: @variant_name.to_s)
+        @_assigned_variant_name ||= :control
+        Variant.new(name: @_assigned_variant_name.to_s)
       end
     ensure
-      @resolving_variant = false
+      @_resolving_variant = false
     end
 
     def rollout(rollout = nil, options = {})
-      return @rollout ||= self.class.default_rollout(nil, options) if rollout.blank?
+      return @_rollout ||= self.class.default_rollout(nil, options).for(self) if rollout.blank?
 
-      @rollout = Rollout.resolve(rollout).new(options)
+      @_rollout = Rollout.resolve(rollout).new(options).for(self)
     end
 
     def exclude!
-      @excluded = true
+      @_excluded = true
     end
 
     def run(variant_name = nil)
-      @result ||= super(variant(variant_name).name)
-    rescue Scientist::BehaviorMissing => e
-      raise Error, e
+      return @_result if context.frozen?
+
+      @_result = run_callbacks(run_callback_chain) { super(assigned(variant_name).name) }
     end
 
-    def publish(result)
+    def publish(result = nil)
       instance_exec(result, &Configuration.publishing_behavior)
 
       (RequestStore.store[:published_gitlab_experiments] ||= {})[name] = signature.merge(excluded: excluded?)
@@ -117,7 +167,7 @@ module Gitlab
     def track(action, **event_args)
       return unless should_track?
 
-      instance_exec(action, event_args, &Configuration.tracking_behavior)
+      instance_exec(action, tracking_context(event_args).try(:compact) || {}, &Configuration.tracking_behavior)
     end
 
     def process_redirect_url(url)
@@ -128,33 +178,31 @@ module Gitlab
     end
 
     def enabled?
-      true
+      rollout.enabled?
     end
 
     def excluded?
-      return @excluded if defined?(@excluded)
+      return @_excluded if defined?(@_excluded)
 
-      @excluded = !run_callbacks(:exclusion_check) { :not_excluded }
-    end
-
-    def experiment_group?
-      instance_exec(@variant_name, &Configuration.inclusion_resolver)
+      @_excluded = !run_callbacks(exclusion_callback_chain) { :not_excluded }
     end
 
     def should_track?
-      enabled? && @context.trackable? && !excluded?
+      enabled? && context.trackable? && !excluded?
     end
 
     def signature
-      { variant: variant.name, experiment: name }.merge(context.signature)
+      { variant: assigned.name, experiment: name }.merge(context.signature)
     end
 
     def key_for(source, seed = name)
-      # TODO: Added deprecation in release 0.6.0
+      # TODO: Remove - deprecated in release 0.7.0
       if (block = Configuration.instance_variable_get(:@__context_hash_strategy))
         return instance_exec(source, seed, &block)
       end
 
+      return source if source.is_a?(String)
+
       source = source.keys + source.values if source.is_a?(Hash)
 
       ingredients = Array(source).map { |v| identify(v) }
@@ -169,14 +217,27 @@ module Gitlab
       (object.respond_to?(:to_global_id) ? object.to_global_id : object).to_s
     end
 
-    def segmentation_callback_chain
-      return :segmentation_check if @variant_name.nil? && enabled? && !excluded?
-
-      :unsegmented
+    def resolve_variant_name
+      if respond_to?(:experiment_group?, true)
+        # TODO: Remove - deprecated in release 0.7.0
+        Configuration.deprecated(:experiment_group?, <<~MESSAGE, version: '0.7.0')
+          instead put this logic into custom rollout strategies
+        MESSAGE
+
+        rollout.resolve if experiment_group?
+      elsif (block = Configuration.instance_variable_get(:@__inclusion_resolver))
+        # TODO: Remove - deprecated in release 0.7.0
+        rollout.resolve if instance_exec(@_assigned_variant_name, &block)
+      elsif (block = Configuration.instance_variable_get(:@__variant_resolver))
+        # TODO: Remove - deprecated in release 0.6.5
+        instance_exec(@_assigned_variant_name, &block)
+      else
+        rollout.resolve # this is the end result of all deprecations
+      end
     end
 
-    def resolve_variant_name
-      rollout.rollout_for(self) if experiment_group?
+    def tracking_context(event_args)
+      {}.merge(event_args)
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gitlab-experiment
 version: !ruby/object:Gem::Version
-  version: 0.6.2
+  version: 0.7.0
 platform: ruby
 authors:
 - GitLab
@@ -38,26 +38,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.0'
-- !ruby/object:Gem::Dependency
-  name: scientist
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.6'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.6.0
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.6'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.6.0
 description: 
 email:
 - gitlab_rubygems@gitlab.com
@@ -65,53 +45,56 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- lib/generators/gitlab
-- lib/generators/gitlab/experiment
-- 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/application_experiment.rb.tt
-- lib/generators/gitlab/experiment/install/templates/initializer.rb.tt
-- lib/generators/gitlab/experiment/install/templates/POST_INSTALL
-- lib/generators/gitlab/experiment/USAGE
-- lib/generators/gitlab/experiment/experiment_generator.rb
-- lib/generators/gitlab/experiment/templates
-- lib/generators/gitlab/experiment/templates/experiment.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/generators/test_unit/experiment/experiment_generator.rb
 - 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/gitlab/experiment.rb
+- lib/generators/rspec/experiment/experiment_generator.rb
+- lib/generators/gitlab
+- lib/generators/gitlab/experiment
+- lib/generators/gitlab/experiment/USAGE
+- lib/generators/gitlab/experiment/templates
+- lib/generators/gitlab/experiment/templates/experiment.rb.tt
+- lib/generators/gitlab/experiment/install
+- lib/generators/gitlab/experiment/install/templates
+- lib/generators/gitlab/experiment/install/templates/application_experiment.rb.tt
+- lib/generators/gitlab/experiment/install/templates/initializer.rb.tt
+- lib/generators/gitlab/experiment/install/templates/POST_INSTALL
+- lib/generators/gitlab/experiment/install/install_generator.rb
+- lib/generators/gitlab/experiment/experiment_generator.rb
 - lib/gitlab/experiment
-- lib/gitlab/experiment/variant.rb
-- lib/gitlab/experiment/middleware.rb
+- lib/gitlab/experiment/dsl.rb
+- lib/gitlab/experiment/rspec.rb
+- lib/gitlab/experiment/context.rb
+- lib/gitlab/experiment/nestable.rb
+- lib/gitlab/experiment/configuration.rb
+- lib/gitlab/experiment/rollout.rb
 - lib/gitlab/experiment/cache
 - lib/gitlab/experiment/cache/redis_hash_store.rb
-- lib/gitlab/experiment/errors.rb
-- lib/gitlab/experiment/callbacks.rb
-- lib/gitlab/experiment/rollout.rb
-- lib/gitlab/experiment/base_interface.rb
-- lib/gitlab/experiment/context.rb
 - lib/gitlab/experiment/engine.rb
-- lib/gitlab/experiment/rspec.rb
+- lib/gitlab/experiment/base_interface.rb
+- lib/gitlab/experiment/middleware.rb
+- lib/gitlab/experiment/version.rb
+- lib/gitlab/experiment/cookies.rb
+- lib/gitlab/experiment/errors.rb
+- lib/gitlab/experiment/cache.rb
+- lib/gitlab/experiment/variant.rb
 - lib/gitlab/experiment/rollout
 - lib/gitlab/experiment/rollout/random.rb
-- lib/gitlab/experiment/rollout/round_robin.rb
 - lib/gitlab/experiment/rollout/percent.rb
-- lib/gitlab/experiment/cache.rb
-- lib/gitlab/experiment/version.rb
-- lib/gitlab/experiment/cookies.rb
-- lib/gitlab/experiment/configuration.rb
-- lib/gitlab/experiment/dsl.rb
+- lib/gitlab/experiment/rollout/round_robin.rb
+- lib/gitlab/experiment/callbacks.rb
+- lib/gitlab/experiment/test_behaviors
+- lib/gitlab/experiment/test_behaviors/trackable.rb
+- lib/gitlab/experiment.rb
 - LICENSE.txt
 - README.md
-homepage: https://gitlab.com/gitlab-org/gitlab-experiment
+homepage: https://gitlab.com/gitlab-org/ruby/gems/gitlab-experiment
 licenses:
 - MIT
 metadata: {}
@@ -130,8 +113,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
+rubygems_version: 3.1.6
 signing_key: 
 specification_version: 4
-summary: GitLab experiment library built on top of scientist.
+summary: GitLab experimentation library.
 test_files: []