experimental 0.1.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    Zjc0ZjhjZGU1OTRjYzA0YjY2MjM2NDVhOTQ2NjY1MGJjNjFiZWUyYg==
+  data.tar.gz: !binary |-
+    N2Q1ZDM5OTk4NWYyMzNmYjY5OWNlOWVjNzFlMTUxYzZjMjRlZTUyNg==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    ZGVmMGFjYWNkZWExMGJmNWRiNmVmMjRiZWQzMTUyNGFhZGRmNThiODI2MTg3
+    NTQzMjI4NzBmZGJkNmFlNDI5YTM2MThmMmJkY2JiZWVkODBhZTcyZmM0OWVm
+    NzQzNGUwOGMwMGVjZjhiM2QzM2NhNmQxYTAyMDJhNTI3NzIyNjE=
+  data.tar.gz: !binary |-
+    N2Q3ZjM1OWRjN2NiMzA4ZWExYWU5ODY0ZDcxMjA5NTgzOWI4OWE2OWIzNmJk
+    MjM1Njk1NTk4Mjc1NWRmNzM4N2YwM2M1YjViZmRlODFlMDIxOWRkM2I1NmU3
+    MWNiODNhMmEzOGZhMDBkM2JlMDY1MjRkN2Q5MTNjYWEyZDQ1ZmU=

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2013 This Life, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.markdown

@@ -0,0 +1,337 @@
+# Experimental
+Experimental is an Split testing framework for Rails.  
+It was written with a few goals in mind:
+* Split the users in a non-predictable pattern (i.e. half of the users won't always
+be in all experiments)
+* Keep experiments and their start and end dates in the database
+* Have a clear developer workflow, so that tests in the code are
+  started in the database when the code goes out and tests that should
+be removed make the site explode
+* Allow admins to end experiments and set a winner
+* Cache the experiments
+
+## Installation
+
+```rails g experimental```
+
+### Routes
+
+````
+    resources :experiments, :only => [:index, :new, :create] do
+      collection do
+        get :inactive
+        post :set_winner
+      end
+    end
+````
+
+````
+    namespace :singles_admin do
+      resources :experiments, :only => [:index, :new, :create] do
+        collection do
+          get :inactive
+          post :set_winner
+        end
+      end
+    end
+````
+
+### Admin Frontend
+
+#### Create your own admin controller:
+````
+    class Admin::ExperimentsController < ApplicationController
+      include Experimental::ControllerActions
+
+      alias_method :index, :experiments_index
+      alias_method :new, :experiments_new
+      alias_method :set_winner, :experiments_set_winner
+
+      def create
+        if experiments_create
+          redirect_to admin_experiments_path
+        else
+          render :new
+        end
+      end
+
+      def base_resource_name
+        "singles_admin_experiment"
+      end
+
+    end
+````
+
+#### Using ActiveAdmin:
+
+``` rails g active_admin:resource Experiment```
+
+````
+    require 'experimental/controller_actions'
+
+    ActiveAdmin.register Experimental::Experiment, as: "Experiment" do
+      actions :index, :new, :create
+      filter :name
+
+      controller do
+        class_eval do
+          include Experimental::ControllerActions
+        end
+
+        def base_resource_name
+          "admin_experiment"
+        end
+
+        def create
+          if experiments_create
+            redirect_to admin_experiments_path
+          else
+            render :new
+          end
+        end
+
+        def new
+          experiments_new
+        end
+      end
+
+     # collection_actions force active_admin to create a route
+     collection_action :set_winner, method: :post do
+        experiments_set_winner
+      end
+
+      # can do this instead of the ended_or_removed scope below
+      # you will need to add a link to inactive_admins_experiments_path
+      #  in your view
+      collection_action :inactive do
+        experiments_inactive
+        render template: 'admin/experiments/index'
+      end
+
+      scope :in_progress, :default => true do |experiments|
+        experiments.in_progress
+      end
+
+      scope :ended_or_removed do |experiments|
+        @include_inactive = true
+        experiments.ended_or_removed
+      end
+
+      index do
+        render template: 'admin/experiments/index'
+      end
+
+      form :partial => 'new'
+    end
+
+````
+
+#### Views
+
+create an index and new view in appropriate view folder, i.e.
+
+``` app/views/admin/experiments/index.html.erb ```
+````
+    <%= render partial: 'experimental/links' %>
+    <%= render partial: 'experimental/index' %>
+````
+
+``` app/views/admin/experiments/new.html.erb ```
+````
+    <%= render partial: 'experimental/links' %>
+    <%= render partial: 'experimental/new' %>
+````
+
+*Note: ActiveAdmin users will not need to include the links
+  partials*
+
+### Subject
+
+For the class you'd like to be the subject of experiments, include the
+Experimental::Subject module in a model with an id and timestamps
+````
+    class User < ActiveRecord::Base
+        include Experimental::Subject
+        ...
+````
+
+
+## Usage
+
+### Create an experiment
+
+In `config/experiments.yml`, add the name, num_buckets, and notes of the
+experiment under in_code:
+````
+in_code:
+-
+  name: :price_experiment
+  num_buckets: 2
+  notes: |
+    0: $22
+    1: $19.99
+
+````
+Then run `rake experiments:sync`
+
+### Using the experiment
+
+To see if a user is in the experiment population AND in a bucket:
+````
+    #checks if the user is in the my_experiment population
+    #  and if they are in bucket 0
+    user.in_bucket?(:my_experiment, 0)
+````
+
+To see if a user is in the experiment population **ONLY**
+````
+    user.in_experiment?(:my_experiment)
+````
+
+### Ending an experiment
+
+You can end an experiment by setting the end_date.  In the admin
+interface, there is a dropdown to set the end date. When ending an
+experiment *you must set a winning bucket*
+
+*Ending an experiment means that all users will be given the winning
+bucket*
+
+### Removing an experiment
+
+A removed experiment is an experiment that is not referenced
+anywhere in code.  In fact, the framework will throw an exception
+if you reference an experiment that is not in code.
+
+Moving an experiment from the in_code to the removed section of
+`config/experiments.yml` and running `rake experiments:sync` will
+remove the experiment and expire the cache.
+
+````
+removed:
+-
+  name: :price_experiment
+````
+Then run `rake experiments:sync`
+
+
+
+## Testing
+
+### Setup
+in ```spec_helper.rb``` (after inclusion of ActiveSupport)
+
+````
+    require 'experimental/rspec_helpers'
+````
+
+*You may want to force experiments off for all tests by default*
+````
+    config.before(:each) do
+      User.any_instance.stub(:in_experiment?).and_return(false)
+    end
+````
+
+### Testing experiments
+
+Include the Rspec helpers in your spec class or spec_helper
+````
+    include Experimental::RspecHelpers
+````
+
+Shared contexts are available for in_experiment? and in_bucket?
+````
+    include_context "in experiment"
+    include_context "not in experiment"
+    
+    include_context "in experiment bucket 0"
+    include_context "in experiment bucket 1"
+```
+
+Helper methods are also available:
+
+**is_in_experiment**
+````
+    # first param is true for in experiment, false for not in
+experiment
+    # second param is the experiment name
+    # third param is the subject object
+    is_in_experiment(true, :my_experiment, my_subject)
+    
+    # if user and experiment_name are defined, you can do
+    let(:experiment_name) { :my_experiment }
+    let(:user) { User.new }
+    is_in_experiment # true if in experiment
+    is_in_experiment(false) # true if NOT in experiment
+````
+
+**is_not_in_experiment**
+````
+    # first param is name of experiment
+    # second param is subject object
+    is_not_in_experiment(:my_experiment, my_subject)
+
+    # if user and experiment_name are defined, you can do
+    let(:experiment_name) { :my_experiment }
+    let(:user) { User.new }
+    is_not_in_experiment
+````
+
+**has_experiment_bucket**
+````
+    has_experiment_bucket(1, :my_experiment, my_subject)
+
+    # if user and experiment_name are defined, you can do
+    let(:experiment_name) { :my_experiment }
+    let(:user) { User.new }
+    has_experiment_bucket(1)
+
+````
+
+
+
+## Developer Workflow
+
+Experiments *can* be defined in config/experiments.yml
+Running the rake task `rake experiments:sync` will load those
+experiments under 'in_code' into the database and set removed_at
+timestamp for those under 'removed'
+
+You will likely want to automate the running of `rake
+experiments:sync` by adding to your deploy file.
+
+### Capistrano
+In `config/deploy.rb`:
+
+Create a namespace to run the task:
+````
+    namespace :database do
+      desc "Sync experiments"
+      task :sync_from_app, roles: :db, only: { primary: true } do
+        run "cd #{current_path} && RAILS_ENV=#{rails_env} bundle exec rake experiments:sync"
+      end
+    end
+````
+
+Include that in the deploy:default task:
+````
+    namespace :deploy do
+      ...
+      task :default do
+        begin
+          update_code
+          migrate
+          database.sync_from_app
+          restart
+       ...
+````
+
+### Admin created experiments
+
+The purpose of Admin created experiments are for experiments
+that will flow through to another system, such as an email provider.
+They likely start with a known string and are dynamically sent in
+code.
+Otherwise, Admin created experiments will do nothing as their is no
+code attached to them. 
+

data/Rakefile

@@ -0,0 +1,19 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'spec'
+  t.pattern = 'spec/**/*_spec.rb'
+  t.verbose = false
+end
+
+
+task :default => :test

data/app/models/experimental/cache.rb

@@ -0,0 +1,69 @@
+module Experimental
+  class Cache
+    cattr_accessor :interval
+    cattr_reader :last_check
+    cattr_reader :last_update
+    cattr_reader :experiments
+    cattr_accessor :cache_race_condition_ttl
+    @@cache_race_condition_ttl = 10
+    cattr_accessor :cache_key
+
+    class << self
+      def get(name)
+        unless within_interval?
+          if need_update?(last_cached_update)
+            @@experiments = experiments_to_hash(Experiment.in_code)
+            @@last_update = Time.now
+          end
+        end
+        experiments[name.to_sym]
+      end
+
+      def [](name)
+        get(name)
+      end
+
+      def interval
+        @@interval ||= 5.minutes
+      end
+
+      def last_check
+        @@last_check ||=
+          Time.now - interval - 1.minute
+      end
+
+      def last_update
+        @@last_update ||= last_cached_update
+      end
+
+      def cache_key
+        @@cache_key ||= "experiments_last_update"
+      end
+
+      def within_interval?
+        (Time.now - last_check) < interval
+      end
+
+      def need_update?(last_cached_update_time)
+        experiments.nil? || last_update < last_cached_update_time
+      end
+
+      def experiments_to_hash(experiments)
+        HashWithIndifferentAccess.new.tap do |h|
+          experiments.each { |e| h[e.name.to_sym] = e }
+        end
+      end
+
+      def last_cached_update
+        # setting a default to 1 minute ago will force all servers to update
+        Rails.cache.fetch(cache_key, :race_condition_ttl => cache_race_condition_ttl ) do
+          Experiment.last_updated_at || 1.minute.ago
+        end
+      end
+
+      def expire_last_updated
+        Rails.cache.delete(cache_key)
+      end
+    end
+  end
+end

data/app/models/experimental/experiment.rb

@@ -0,0 +1,114 @@
+module Experimental
+  class Experiment < ActiveRecord::Base
+    extend Population::Filter
+
+    cattr_accessor :use_cache
+    @@use_cache = true
+
+    attr_accessible :name, :num_buckets, :notes
+
+    validates_presence_of :name, :num_buckets
+    validates_numericality_of :num_buckets, :greater_than_or_equal_to => 2
+    validates_numericality_of :winning_bucket,
+      :greater_than_or_equal_to => 0,
+      :less_than => :num_buckets,
+      :if => :ended?
+
+    after_create :expire_cache
+
+    def self.in_code
+      where(:removed_at => nil)
+    end
+
+    def self.in_progress
+      where('removed_at is null and end_date is null').
+        order('start_date desc').
+        order(:name)
+    end
+
+    def self.ended_or_removed
+      where('removed_at is not null or end_date is not null').
+        order(:removed_at).
+        order('end_date desc')
+    end
+
+    def self.last_updated_at
+      maximum(:updated_at)
+    end
+
+    def self.[](experiment_name)
+      if use_cache
+        Cache.get(experiment_name)
+      else
+        find_by_name(experiment_name.to_s)
+      end
+    end
+
+    def self.expire_cache
+      Cache.expire_last_updated if use_cache
+    end
+
+    def expire_cache
+      Experiment.expire_cache
+    end
+
+    def bucket(subject)
+      (ended? || removed?) ? winning_bucket : bucket_number(subject)
+    end
+
+    def in?(subject)
+      return false if removed?
+      population_filter.in?(subject, self)
+    end
+
+    def end(winning_num)
+      self.winning_bucket = winning_num
+      self.end_date = Time.now
+      result = save
+
+      Experiment.expire_cache if result
+
+      result
+    end
+
+    def remove
+      result = false
+
+      unless removed?
+        result = update_attributes(
+          { removed_at: Time.now }, without_protection: true
+        )
+        expire_cache if result
+      end
+
+      result
+    end
+
+    def removed?
+      !removed_at.nil?
+    end
+
+    def ended?
+      !end_date.nil? && Time.now > end_date
+    end
+
+    def active?
+      !removed? && !ended?
+    end
+
+    def to_sql_formula(subject_table = "users")
+      "CONV(SUBSTR(SHA1(CONCAT(\"#{name}\",#{subject_table}.id)),1,8),16,10) % #{num_buckets}"
+    end
+
+    def bucket_number(subject)
+      top_8 = Digest::SHA1.hexdigest("#{name}#{subject.id}")[0..7]
+      top_8.to_i(16) % num_buckets
+    end
+
+    private
+
+    def population_filter
+      @population_filter ||= self.class.find_population(population)
+    end
+  end
+end

data/app/models/experimental/loader.rb

@@ -0,0 +1,64 @@
+module Experimental
+  class Loader
+    cattr_accessor :file_path
+    @@file_path = 'config/experiments.yml'
+
+    @@whitelisted_attributes = [:name, :num_buckets, :notes, :population]
+
+    class << self
+      def sync(verbose = false)
+        puts "Loading experiments ..." if verbose
+        experiments = load_experiments
+
+        #new/active
+        experiments.in_code.each do |exp|
+          name = exp.with_indifferent_access[:name]
+          puts "\tUpdating #{name} ..." if verbose
+
+          exp = whitelisted_attrs(exp)
+          e = Experimental::Experiment.find_by_name(name) || Experimental::Experiment.new
+
+          puts "\t\tcreating ..." if verbose && e.id.nil?
+          puts "\t\tupdating ..." if verbose && !e.id.nil?
+
+          exp.merge!({ start_date: Time.now }) if e.start_date.nil?
+          e.update_attributes!(exp, without_protection: true)
+        end unless experiments.in_code.nil?
+
+        #removed
+        experiments.removed.each do |exp|
+          name = exp.with_indifferent_access[:name]
+          puts "\tRemoving #{name} ..." if verbose
+
+          exp = whitelisted_attrs(exp)
+          e = Experimental::Experiment.find_by_name(name)
+
+          if e && e.removed_at.nil?
+            puts "\t\t#{name} exists, removing ..." if verbose
+            result = e.remove
+            puts "\t\t\t#{result}" if verbose
+          else
+            puts "\t\t#{name} doesn't exist!" if verbose
+          end
+        end unless experiments.removed.nil?
+
+        puts "Expiring cache ..." if verbose
+        Experimental::Experiment.expire_cache
+
+        puts "Done syncing experiments!" if verbose
+      end
+
+      private
+
+      def load_experiments
+        OpenStruct.new YAML.load_file(File.join(Rails.root, file_path))
+      end
+
+      def whitelisted_attrs(exp)
+        exp.
+          select { |k, v| @@whitelisted_attributes.include?(k.to_sym) }.
+          with_indifferent_access
+      end
+    end
+  end
+end

data/app/models/experimental/population/default.rb

@@ -0,0 +1,12 @@
+# This class will filter the population of an experiment
+# Override in? to filter the population
+# Called by Experiment.in?
+module Experimental
+  module Population
+    class Default
+      def self.in?(obj, experiment)
+        true
+      end
+    end
+  end
+end

data/app/models/experimental/population/filter.rb

@@ -0,0 +1,33 @@
+module Experimental
+  module Population
+    module Filter
+      def self.extended(base)
+        base.reset_population_filters
+      end
+
+      def find_population(name)
+        if name.blank?
+          Experimental::Population::Default
+        else
+          filter_classes[name.to_s]
+        end
+      end
+
+      def register_population_filter(name, filter_class)
+        filter_classes[name.to_s] = filter_class
+      end
+
+      def reset_population_filters
+        filter_classes.clear
+        register_population_filter(:new_users, NewUsers)
+        register_population_filter(:default, Default)
+      end
+
+      private
+
+      def filter_classes
+        @filter_classes ||= {}
+      end
+    end
+  end
+end

data/app/models/experimental/population/new_users.rb

@@ -0,0 +1,9 @@
+module Experimental
+  module Population
+    class NewUsers
+      def self.in?(subject, experiment)
+        subject.created_at >= experiment.start_date
+      end
+    end
+  end
+end

data/app/models/experimental/subject.rb

@@ -0,0 +1,19 @@
+module Experimental
+  module Subject
+    def in_experiment?(name)
+      Experiment[name].try { |e| e.in?(self) }
+    end
+
+    def not_in_experiment?(name)
+      !in_experiment?(name)
+    end
+
+    def experiment_bucket(name)
+      Experiment[name].try { |e| e.bucket(self) }
+    end
+
+    def in_bucket?(name, bucket)
+      in_experiment?(name) && experiment_bucket(name) == bucket
+    end
+  end
+end

data/app/views/experimental/_experiment.html.erb

@@ -0,0 +1,16 @@
+<tr>
+  <td><%= experiment.name.humanize %></td>
+  <td><%= "#{experiment.num_buckets} (0-#{experiment.num_buckets-1})" %></td>
+  <td><%= experiment.population || "default" %></td>
+  <td><%= experiment.notes.try(:gsub, "\n", '<br>').try(:html_safe) %></td>
+  <td><%= experiment.start_date.try(:in_time_zone).try(:strftime, "%D %r %Z") %></td>
+  <% if @include_inactive %>
+    <td><%= experiment.winning_bucket %></td>
+    <td><%= experiment.end_date.try(:in_time_zone).try(:strftime, "%D %r %Z") %></td>
+    <td><%= experiment.removed_at.try(:in_time_zone).try(:strftime, "%D %r %Z") %></td>
+  <% else %>
+    <td>
+      <%= hidden_field_tag "exp-#{experiment.id}", experiment.id %>
+      <%= select_tag "exp-#{experiment.id}-buckets", options_for_select((0..experiment.num_buckets-1).to_a.insert(0, ['-- select --', -1])), class: 'set_winner' %>
+    </td>
+  <% end %>

data/app/views/experimental/_index.html.erb

@@ -0,0 +1,50 @@
+<h1><%= @h1 %></h1>
+
+<table>
+  <thead>
+    <tr>
+      <th scope="col"> Name </th>
+      <th scope="col"> Buckets </th>
+      <th scope="col"> Population </th>
+      <th scope="col"> Notes </th>
+      <th scope="col"> Start </th>
+      <th scope="col"> Winner </th>
+      <% if @include_inactive %>
+        <th scope="col"> End </th>
+        <th scope="col"> Removed </th>
+      <% end %>
+    </tr>
+  </thead>
+  <tbody>
+  <%= render partial: 'experimental/experiment', collection: @experiments %>
+  </tbody>
+</table>
+
+<script type="text/javascript">
+  $(function(){
+    $(".set_winner").change(function(){
+      var bucket_id = $(this).val();
+      var msg = "Are you sure you want to end this experiment and set the winning bucket to " + bucket_id;
+
+      if( bucket_id > -1 && confirm(msg) ){
+        var exp_id = $(this).siblings().val(); 
+
+        $.ajax({
+          type: "POST",
+          data: {id:exp_id, bucket_id:bucket_id},
+          url: '<%= @experimental_path_names.set_winner %>',
+          success: function(resp){
+            window.location.reload();
+          },
+          error: function(){
+            alert("WE BLEW UP!");
+            $(this).val(-1);
+          }
+        });
+      }
+      else{
+        $(this).val(-1);
+      }
+    });
+  });
+</script>

data/app/views/experimental/_links.html.erb

@@ -0,0 +1,7 @@
+<div class="experiment_links">
+  <%= link_to "In-progress", @experimental_path_names.index %>
+  |
+  <%= link_to "Ended or Removed", @experimental_path_names.inactive %>
+  |
+  <%= link_to "Create New Experiment", @experimental_path_names.new %>
+</div>

data/app/views/experimental/_new.html.erb

@@ -0,0 +1,37 @@
+<h1> New Experiment</h1>
+<br />
+<%= form_for(@experiment, url: @experimental_path_names.index) do |f| %>
+  <% if @experiment.errors.any? %>
+    <div id="error_explanation">
+      <h2>
+        <%= pluralize(@experiment.errors.count, "error") %>
+        probited this experiment from being saved:
+      </h2>
+      <ul>
+        <% @experiment.errors.full_messages.each do |msg| %>
+          <li><%= msg %></li>
+        <% end %>
+      </ul>
+    </div>
+  <% end %>
+
+  <p class="field">
+    <%= f.label :name %>
+    <br />
+    <%= f.text_field :name %>
+  </p>
+  <p class="field">
+    <%= f.label :num_buckets %>
+    <br />
+    <%= f.text_field :num_buckets %>
+  </p>
+  <p class="field">
+    <%= f.label :notes %>
+    <br />
+    <%= f.text_area :notes, cols: "30", rows: "5" %>
+  </p>
+
+  <p class="actions" >
+    <%= f.submit %>
+  </p>
+<% end %>

data/config/routes.rb

@@ -0,0 +1,2 @@
+Rails.application.routes.draw do
+end

data/lib/experimental/controller_actions.rb

@@ -0,0 +1,89 @@
+require 'ostruct'
+
+module Experimental
+  module ControllerActions
+    extend ActiveSupport::Concern
+
+    included do
+      class_eval do
+        attr_writer :base_resource_name
+
+        respond_to :json, :only => [:set_winner]
+
+        before_filter :set_experimental_path_names
+      end
+    end
+
+    def base_resource_name
+      @base_resource_name ||= "experiment"
+    end
+
+    def set_experimental_path_names
+      @experimental_path_names = OpenStruct.new
+      plural_path = "#{base_resource_name.pluralize}_path"
+
+      @experimental_path_names.index = self.send(plural_path.to_sym)
+      if self.respond_to?("inactive_#{plural_path}".to_sym)
+        @experimental_path_names.inactive = self.send("inactive_#{plural_path}".to_sym)
+      end
+      @experimental_path_names.new = self.send("new_#{base_resource_name}_path".to_sym)
+      @experimental_path_names.set_winner = self.send("set_winner_#{plural_path}".to_sym)
+    end
+
+    def experimental_path_names
+      set_experimental_path_names if @experimental_path_names.nil?
+      @experimental_path_names
+    end
+
+    def experiments_index
+      @h1 = "In-progress Experiments"
+      @include_inactive = false
+      @experiments = Experiment.in_progress
+    end
+
+    def experiments_new
+      @experiment = Experiment.new
+    end
+
+    def experiments_create
+      @experiment = Experiment.new(params[:experimental_experiment])
+      @experiment.start_date = Time.now
+
+      if @experiment.save
+        flash[:notice] = "Experiment was successfully created."
+        return true
+      else
+        flash.now[:error] = "There was an error!"
+        return false
+      end
+    end
+
+    def experiments_inactive
+      @h1 = "Ended or Removed Experiments"
+      @include_inactive = true
+      @experiments = Experiment.ended_or_removed
+    end
+
+    def create
+      if experiments_create
+        redirect_to experimental_path_names.index
+      else
+        render :new
+      end
+    end
+
+    def inactive
+      experiments_inactive
+      render :index
+    end
+
+    def experiments_set_winner
+      exp = Experiment.find params[:id]
+      if exp.end(params[:bucket_id])
+        render json: nil, status: :ok
+      else
+        render json: nil, status: :error
+      end
+    end
+  end
+end

data/lib/experimental/engine.rb

@@ -0,0 +1,4 @@
+module Experimental
+  class Engine < ::Rails::Engine
+  end
+end

data/lib/experimental/rspec_helpers.rb

@@ -0,0 +1,56 @@
+module Experimental
+  module RspecHelpers
+    extend ::ActiveSupport::Concern
+
+    def is_in_experiment(val = true, name = nil, obj = nil)
+      obj ||= user
+      name ||= experiment_name
+
+      obj.should_receive(:in_experiment?).any_number_of_times.
+        with(name).and_return(val)
+    end
+
+    def is_not_in_experiment(name = nil, obj = nil)
+      obj ||= user
+      name ||= experiment_name
+
+      is_in_experiment(false, name, obj)
+    end
+
+    def has_experiment_bucket(bucket, name = nil, obj = nil)
+      obj ||= user
+      name ||= experiment_name
+
+      obj.should_receive(:experiment_bucket).any_number_of_times.
+        with(name).and_return(bucket)
+    end
+  end
+
+  module ClassMethods
+    shared_context "in experiment" do
+      before do
+        is_in_experiment
+      end
+    end
+
+    shared_context "not in experiment" do
+      before do
+        is_not_in_experiment
+      end
+    end
+
+    shared_context "in experiment bucket 1" do
+      include_context "in experiment"
+      before do
+        has_experiment_bucket(1)
+      end
+    end
+
+    shared_context "in experiment bucket 0" do
+      include_context "in experiment"
+      before do
+        has_experiment_bucket(0)
+      end
+    end
+  end
+end

data/lib/experimental/version.rb

@@ -0,0 +1,11 @@
+module Experimental
+  VERSION = [0, 1, 0]
+
+  class << VERSION
+    include Comparable
+
+    def to_s
+      join('.')
+    end
+  end
+end

data/lib/experimental.rb

@@ -0,0 +1,11 @@
+require 'rails'
+require 'experimental/engine'
+
+module Experimental
+  autoload :VERSION, 'experimental/version'
+  autoload :ControllerActions, 'experimental/controller_actions'
+
+  def self.register_population_filter(name, filter_class)
+    Experiment.register_population_filter(name, filter_class)
+  end
+end

data/lib/generators/experimental/experimental_generator.rb

@@ -0,0 +1,29 @@
+class ExperimentalGenerator < Rails::Generators::Base
+  include Rails::Generators::Migration
+  source_root File.expand_path('../templates', __FILE__)
+
+  desc "copy experiments yaml file"
+  def copy_experiments_yaml
+    copy_file "experiments.yml", "config/experiments.yml"
+  end
+
+  desc "copy initializer"
+  def copy_experiments_initialize
+    copy_file "experimental.rb", "config/initializers/experimental.rb"
+  end
+
+
+  desc "add migrations"
+  def self.next_migration_number(path)
+    if ActiveRecord::Base.timestamped_migrations
+      Time.now.utc.strftime("%Y%m%d%H%M%S").to_i
+    else
+      "%.3d" % (current_migration_number(dirname) + 1)
+    end
+  end
+
+  def copy_migrations
+    migration_template 'create_experiments_table.rb',
+      'db/migrate/create_experiments_table.rb'
+  end
+end

data/lib/generators/experimental/templates/create_experiments_table.rb

@@ -0,0 +1,24 @@
+class CreateExperimentsTable < ActiveRecord::Migration
+  def up
+    create_table :experiments do |t|
+      t.string :name, null: false, limit: 128
+      t.datetime :start_date
+      t.datetime :end_date
+      t.integer :num_buckets, null: false, default: 1
+      t.integer :winning_bucket
+      t.text :notes, limit: 256
+      t.string :population
+      t.datetime :removed_at
+      t.timestamps
+    end
+
+    add_index :experiments, :name, :unique => true
+    add_index :experiments, :start_date
+    add_index :experiments, :population
+    add_index :experiments, :updated_at
+  end
+
+  def down
+    drop_table :experiments
+  end
+end

data/lib/generators/experimental/templates/experimental.rb

@@ -0,0 +1,6 @@
+#Load the population classes
+#Rails lazy loads and since they are never explicitly referenced, they don't get loaded
+#Deleting this file causes failures when running individual specs
+Dir[File.join(Rails.root, 'app/models/experimental/population/*.rb')].each do |f|
+  require f
+end

data/lib/generators/experimental/templates/experiments.yml

@@ -0,0 +1,33 @@
+# run rake experiments:sync to get these into the database
+#   sets start_date to Time.now for experiments in_code
+#   sets removed_at to Time.now for experiments in removed
+
+# these are the experiments with the path still in code
+# note: these could be ended via the Admin
+# Format:
+# -
+#   name: #name of the experiment as symbol
+#   num_buckets: #number of possible buckets (standard a/b test would be 2)
+#   population: #optional
+#       #possible values:
+#           :default or nil = all users
+#           :new_users = users created after start date
+#   notes: #optional. free form notes to see in Admin
+#     # preface this with | in order to have multi-line text
+# Example
+# -
+#   name: :test_experiment
+#   num_buckets: 2
+#   notes: |
+#      0: sees experiment
+#      1: does not see experiment
+in_code:
+
+# copy an experiment to this section when all code paths have been removed
+# removed at date will be set in rake task
+# only in_code experiments are loaded, but just in case ...
+# experiment code throws an exception if you reference a removed experiment
+# Example:
+# -
+#  name: :removed_experiment
+removed:

data/lib/tasks/experiment.rake

@@ -0,0 +1,6 @@
+namespace :experiments do
+  desc "sync experiments from config/experiment.yml into the database"
+  task :sync => :environment do
+    Experimental::Experiment::Loader.sync(true)
+  end
+end

metadata

@@ -0,0 +1,170 @@
+--- !ruby/object:Gem::Specification
+name: experimental
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- HowAboutWe.com
+- Rebecca Miller-Webster
+- Bryan Woods
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-05-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.2.6
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.2.6
+- !ruby/object:Gem::Dependency
+  name: jquery-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  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: rspec-rails
+  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: activeadmin
+  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: sass-rails
+  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: coffee-rails
+  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: AB Test framework for Rails
+email:
+- dev@howaboutwe.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- app/models/experimental/cache.rb
+- app/models/experimental/experiment.rb
+- app/models/experimental/loader.rb
+- app/models/experimental/population/default.rb
+- app/models/experimental/population/filter.rb
+- app/models/experimental/population/new_users.rb
+- app/models/experimental/subject.rb
+- app/views/experimental/_experiment.html.erb
+- app/views/experimental/_index.html.erb
+- app/views/experimental/_links.html.erb
+- app/views/experimental/_new.html.erb
+- config/routes.rb
+- lib/experimental/controller_actions.rb
+- lib/experimental/engine.rb
+- lib/experimental/rspec_helpers.rb
+- lib/experimental/version.rb
+- lib/experimental.rb
+- lib/generators/experimental/experimental_generator.rb
+- lib/generators/experimental/templates/create_experiments_table.rb
+- lib/generators/experimental/templates/experimental.rb
+- lib/generators/experimental/templates/experiments.yml
+- lib/tasks/experiment.rake
+- MIT-LICENSE
+- Rakefile
+- README.markdown
+homepage: http://wwww.github.com/howaboutwe/experimental
+licenses:
+- MIT
+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: []
+rubyforge_project: 
+rubygems_version: 2.0.3
+signing_key: 
+specification_version: 4
+summary: Adds support for database-backed AB tests in Rails apps
+test_files: []
+has_rdoc: