on_ramp 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5a82ddccbd6d2b5a3ccd7bab025d17a1d607efa8defc093fc8f93388463d06f3
+  data.tar.gz: ef4ee283385bbfbdf5529bd8c37279697066e12e0da6b168b4fff4f3e9afc184
+SHA512:
+  metadata.gz: a8b7a6e335b35102d17fa84a400ff7bcbcb234b8d721464d154c863d4a9601cfccbad57d36b0678583a83fad7aa965b27debfa6a30b96c5c21dd2fc53d3b7e1d
+  data.tar.gz: ee95d5381cbfb6b83213ca0394a5b7957a7393e96943aab2d100ddb62733fb0397b82668d49eea7126677ddf272eff1c065c3475742140f6bd0610599cb358ba

data/Gemfile

@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in on_ramp.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,45 @@
+PATH
+  remote: .
+  specs:
+    on_ramp (0.0.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    byebug (11.0.1)
+    coderay (1.1.2)
+    diff-lcs (1.3)
+    gem-release (2.0.3)
+    method_source (0.9.2)
+    pry (0.12.2)
+      coderay (~> 1.1.0)
+      method_source (~> 0.9.0)
+    rake (13.0.0)
+    rspec (3.8.0)
+      rspec-core (~> 3.8.0)
+      rspec-expectations (~> 3.8.0)
+      rspec-mocks (~> 3.8.0)
+    rspec-core (3.8.2)
+      rspec-support (~> 3.8.0)
+    rspec-expectations (3.8.4)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-mocks (3.8.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-support (3.8.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 2.0)
+  byebug
+  gem-release
+  on_ramp!
+  pry
+  rake (~> 13.0)
+  rspec (~> 3.0)
+
+BUNDLED WITH
+   2.1.4

data/README.md

@@ -0,0 +1,95 @@
+# OnRamp
+
+This gem provides two related but distinct pieces of functionality:
+
+1. Percentage ramp ups of experiments that are intended to test load or the like
+2. Segmenting users into a/b variants for experimentation purposes
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'on_ramp'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install on_ramp
+
+## Usage
+
+Configure the gem in an initializer using the configure method
+
+```
+# /initializers/experiment.rb
+OnRamp.configure do |config|
+    config.ab_experiments = "/initializers/experiments.yaml"
+end
+```
+
+Your yaml file will look similar to the below:
+```
+experiment_name:
+ ramp: 20
+ variants:
+   control: 50
+   variant_a: 50
+```
+
+See below for example code.
+
+Simple use case ramping only
+---
+If you want to slowly ramp out a change to a subset of users, the following code is the simplest way to do so. This is not the recommended way to run an experiment. For running an experiment see below `OnRamp.ab_variant`
+```
+# school.rb
+
+def cool_name
+  if OnRamp.ramped?(:experiment_name, owner.id)
+    "COOOL" + name
+  else
+    name
+  end
+end
+```
+As you can see here, the `#ramped?` method will return true if the user is in the ramped up group and false if they aren't. As you adjust the ramping, more users will experience the ramped up code path.
+
+Simple use case experiment
+--
+The `ab_variant` method does not necessarily return a value. It will return `nil` if the unique_id you've passed is not yet ramped up. If you have configured your experiment with 100% ramp, then `#ab_variant` will always return a value.
+```
+def cool_name_experiment
+ case OnRamp.ab_variant(:cool_name, owner.id)
+ when "variant_a"
+   "COOOL" + name
+ when "variant_b"
+   "C000L" + name
+ when "control"
+   control_group_name
+ else
+   name
+ end
+end
+```
+It may be common to have control and non-ramped experiences be the same, it's very easy with the case `else` clause.
+```
+def cool_name_final
+ case Experiment::ab_variant(:cool_name, owner.id)
+ when "variant_a"
+   "COOOL" + name
+ when "variant_b"
+   "C000L" + name
+ else
+   name
+ end
+end
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rspec spec/` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "on_ramp"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/on_ramp.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'on_ramp/bucket'
+require 'on_ramp/configuration'
+require 'on_ramp/ramp'
+
+module OnRamp
+  module_function
+
+  def ramped?(experiment_name:, unique_id:)
+    validate_experiment_name(experiment_name)
+    OnRamp::Ramp.ramped?(experiment_name.to_s, unique_id)
+  end
+
+  def ab_variant(experiment_name:, unique_id:)
+    validate_experiment_name(experiment_name)
+    variant = if !ramped?(
+      experiment_name: experiment_name,
+      unique_id: unique_id
+    )
+                nil
+              else
+                OnRamp::Bucket.get_variant(
+                  experiment_name: experiment_name.to_s,
+                  unique_id: unique_id
+                )
+              end
+
+    OnRamp.configuration.ab_variant_callback_function&.call(
+      experiment_name,
+      variant,
+      unique_id
+    )
+
+    variant
+  end
+
+  class InvalidExperimentName < StandardError; end
+
+  def validate_experiment_name(experiment_name)
+    return if OnRamp.ab_experiments[experiment_name.to_s]
+
+    raise InvalidExperimentName,
+          "The key does not exist: #{experiment_name}"
+  end
+end

data/lib/on_ramp/bucket.rb

@@ -0,0 +1,33 @@
+require 'digest'
+require 'yaml'
+
+module OnRamp
+  module Bucket
+
+    extend self
+
+    def get_variant(experiment_name:, unique_id:)
+      weight = get_weight(
+        unique_id: unique_id, experiment_name: experiment_name
+      )
+
+      running_total = 0.0
+      cfg = OnRamp.ab_experiments[experiment_name]['variants']
+
+      normalize_variants(cfg).each_pair do |variant_name, percentage|
+        running_total += percentage
+        return variant_name if weight <= running_total
+      end
+    end
+
+    def get_weight(unique_id:, experiment_name:, version: nil)
+      md5 = ::Digest::MD5.hexdigest("#{unique_id}-#{experiment_name}-#{version}")
+      md5[0...8].to_i(16).to_f / 0xFFFFFFFF
+    end
+
+    def normalize_variants(variants_cfg)
+      variants_cfg.map { |k, v| [k, v / 100.0] }.to_h
+    end
+
+  end
+end

data/lib/on_ramp/configuration.rb

@@ -0,0 +1,27 @@
+require 'yaml'
+
+module OnRamp
+
+  extend self
+
+  def configuration
+    @configuration ||= Configuration.new
+  end
+
+  def configure
+    yield(configuration)
+  end
+
+  def ab_experiments
+    configuration.ab_experiments
+  end
+
+  class Configuration
+    attr_reader :ab_experiments, :ab_variant_callback_function
+
+    def ab_experiments=(path)
+      @ab_experiments = YAML.safe_load(File.open(path).read)
+    end
+  end
+
+end

data/lib/on_ramp/ramp.rb

@@ -0,0 +1,20 @@
+require 'yaml'
+
+module OnRamp
+  module Ramp
+
+    extend self
+
+    def ramped?(experiment_name, unique_id)
+      ramp_threshold = OnRamp.ab_experiments[experiment_name.to_s]\
+        ['ramp'] / 100.0
+      weight = OnRamp::Bucket.get_weight(
+        unique_id: unique_id,
+        experiment_name: experiment_name,
+        version: 'ramp'
+      )
+
+      ramp_threshold > weight
+    end
+  end
+end

data/lib/on_ramp/version.rb

@@ -0,0 +1,3 @@
+module OnRamp
+  VERSION = '0.0.1'
+end

data/on_ramp.gemspec

@@ -0,0 +1,30 @@
+lib = File.expand_path("lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "on_ramp/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "on_ramp"
+  spec.version       = OnRamp::VERSION
+  spec.authors       = ["Michael Sterling", "Rhoen Pruesse-Adams", "James Lee"]
+  spec.email         = ["michael@teachable.com", "rhoen@teachable.com", "james@teachable.com"]
+
+  spec.summary       = "An internal Teachable library for ramping up experiments incrementally and segmenting users in A/B tests"
+
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|experiments)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # development dependencies
+  spec.add_development_dependency "bundler", "~> 2.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "pry"
+  spec.add_development_dependency "byebug"
+  spec.add_development_dependency "gem-release"
+end

metadata

@@ -0,0 +1,142 @@
+--- !ruby/object:Gem::Specification
+name: on_ramp
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Michael Sterling
+- Rhoen Pruesse-Adams
+- James Lee
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2020-03-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: gem-release
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email:
+- michael@teachable.com
+- rhoen@teachable.com
+- james@teachable.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- Gemfile.lock
+- README.md
+- bin/console
+- bin/setup
+- lib/on_ramp.rb
+- lib/on_ramp/bucket.rb
+- lib/on_ramp/configuration.rb
+- lib/on_ramp/ramp.rb
+- lib/on_ramp/version.rb
+- on_ramp.gemspec
+homepage: 
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.6
+signing_key: 
+specification_version: 4
+summary: An internal Teachable library for ramping up experiments incrementally and
+  segmenting users in A/B tests
+test_files: []