blackbeard 0.0.2.0 → 0.0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 613ebf477638192eb2ab160882e277bb3b6d0f1a
-  data.tar.gz: 55fea491870b73d48e81ff393a7ae2ba22f337d1
+  metadata.gz: be704d408f74d3fed4eceb91f873c087967ed947
+  data.tar.gz: 33e1a39fe2efeea751f99b9e769e00c72b19e99e
 SHA512:
-  metadata.gz: 05a94bcd373c3c302a64179489a6b1efc3bd58980684f7afcd8200a690663fb9e7daed6ab01c9d5d4f3fae946d11e03326298d938ac94e24057a6da8e08d38dc
-  data.tar.gz: 49f3612b4a6c53f0a5c8b6910ee585e17473e30071ec778318aa6a4715ea3a756ef025f8fb091f4a522a490cae6b87f0686828f72f7e1788f0202e7f79e30b7d
+  metadata.gz: 33d585c054f11b46334cfdbd98907d0b659decd5b4df3d06172b6c44c365ad97500461be00f7d10324ca9499f7620786271a5b22745fca72f39fb6758dbd55f5
+  data.tar.gz: d932724e9091f21dd1c16557cd821ac9a3c7b380391b362d0582a1cf80166381fae3cb07816dbe15f5e2fb5cff8169ede3087ae5b8d0ce9d8568dd5a56ea0271

data/.travis.yml

@@ -0,0 +1,9 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 2.0.0
+services:
+  - redis-server
+addons:
+    code_climate:
+        repo_token: c4f9d40da5073ae61d9bea245b5602eb70566eab3e47248b68dcccc25cb79b56

data/Guardfile

@@ -0,0 +1,8 @@
+guard :rspec, cmd: 'bundle exec rspec' do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/blackbeard/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
+  watch(%r{^dashboard/routes/(.+)\.rb$}) { |m| "spec/dashboard/#{m[1]}_spec.rb" }
+  watch(%r{^dashboard/views/(.+)/.+\.erb$}) { |m| "spec/dashboard/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+end
+

data/README.md

@@ -2,6 +2,8 @@
 
 Blackbeard is a Redis backed metrics collection system with a Rack dashboard.
 
+[![Code Climate](https://codeclimate.com/repos/5300f44be30ba0790d01b5a7/badges/b912a89a38a56f61398a/gpa.png)](https://codeclimate.com/repos/5300f44be30ba0790d01b5a7/feed) [![Code Climate](https://codeclimate.com/repos/5300f44be30ba0790d01b5a7/badges/b912a89a38a56f61398a/coverage.png)](https://codeclimate.com/repos/5300f44be30ba0790d01b5a7/feed) [![Build Status](https://travis-ci.org/goldstar/blackbeard.png?branch=master)](https://travis-ci.org/goldstar/blackbeard)
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -18,27 +20,97 @@ Or install it yourself as:
 
 ## Usage
 
-In an initializer create your global $pirate and pass in your configuration.
+All Blackbeard operations are done via the global `$pirate` which you should initialize early in your app.
+
+### Rails
+
+To configure Rails 3+ create an initializer in `config/initializers`
 
 ```ruby
 require 'blackbeard'
 require 'blackbeard/dashboard'
 
 $pirate = Blackbeard.pirate do |config|
-  config.redis = Redis.new # required. Will automatically be namespaced.
-  config.namespace = "Blackbeard" # optional
-  config.timezone = "America/Los_Angeles" # optional
+  # see configuration options below
+end
+```
+
+And inside your ApplicationController:
+
+```ruby
+before_filter { |c| $pirate.set_context(c.current_user, c.request) }, :unless => robot?
+after_filter{ |c| $pirate.clear_context }
+```
+
+### Sinatra
+
+To configure Sinatra
+
+```ruby
+require 'blackbeard'
+require 'blackbeard/dashboard'
+
+class MySinatraApp < Sinatra::Base
+  enable :sessions
+
+  $pirate = Blackbead.pirate do |config|
+    # see configuration options below
+  end
+
+  before do
+    $pirate.set_context(current_user, self) unless robot?
+  end
+
+  after do
+    $pirate.clear_context
+  end
+
+  ...
 end
 ```
 
+### Configuration options
+
+```ruby
+  $pirate = Blackbeard.pirate do |config|
+    config.redis = Redis.new # required. Will automatically be namespaced.
+    config.namespace = "Blackbeard" # optional
+    config.timezone = "America/Los_Angeles" # optional
+    config.guest_method = :guest? # optional method to call on user objects if they are guests or visitors
+  end
+```
+
 Note that the configuration is shared by all pirates, so only create one pirate at a time.
 
+### Mounting the dashboard
+
 To get the rack dashboard on Rails, mount it in your `routes.rb`. Don't forget to protect it with some constraints.
 
 ```ruby
 mount Blackbeard::Dashboard => '/blackbeard', :constraints => ConstraintClassYouCreate.new
 ```
 
+### Setting Context
+
+Most of Blackbeard's calls are done via a context.
+
+In a web request, this is handled by a before filter:
+
+```ruby
+before_filter { |controller| $pirate.set_context(controller.current_user, controller) }, :unless => robot?
+after_filter { |controller| $pirate.clear_context }
+```
+
+Outside of a web request--or if you want to reference a user other than the one in the current request (e..g referrals)--you set the context before each call to `$pirate`.
+
+```ruby
+$pirate.context(user).add_metric(:referral)
+```
+
+If a context does not exist, `$pirate` will silently ignore all actions. This is useful for dealing with bots.
+
+If the user is unidentied set user to nil or false. If your app can return a Guest object for unidentied users, see the guest configuration setting.
+
 ### Collecting Metrics
 
 In your app, have your pirate collect the important metrics.
@@ -48,7 +120,7 @@ In your app, have your pirate collect the important metrics.
 Unique counts are for metrics wherein a user may trigger the same metric twice, but should only be counted once.
 
 ```ruby
-$pirate.context(:user_id => user_id, :cookies => cookies).add_unique(:logged_in_user)
+$pirate.add_unique(:logged_in_user)
 ```
 
 #### Counting Non-Unique Metrics
@@ -56,38 +128,108 @@ $pirate.context(:user_id => user_id, :cookies => cookies).add_unique(:logged_in_
 Non-unique counts are for metrics wherein a user may trigger the same metric multiple times and the amounts are summed up.
 
 ```ruby
-$pirate.context(...).add_total(:like, +1)                      # increment a like
-$pirate.context(...).add_total(:like, -1)                      # de-increment a like
-$pirate.context(...).add_total(:revenue, +119.95)              # can also accept floats
+$pirate.add_total(:like, +1)                      # increment a like
+$pirate.add_total(:like, -1)                      # de-increment a like
+$pirate.add_total(:revenue, +119.95)              # can also accept floats
 ```
 
-### Setting Context
+### Chaining Metrics
 
-Most of Blackbeard's calls are done via a context.
+Context methods that inrement metrics always return the context, so you can chain them together.
+
+```ruby
+$pirate.set_context(user)
+$pirate.add_total(:like, +1).add_unique(:likers)
+
+$pirate.context(user).add_total(:like, +1).add_unique(:likers)
+```
+
+
+### Defining Tests (changes or features)
+
+Features are defined in your views, controller or anywhere in your app via the global $pirate.  There is no configuration necessary (but see the gotcha below).
+
+
+In a view:
+
+```erb
+<%= $pirate.ab_test(:new_onboarding, :control => '/onboarding', :welcome_flow => '/welcome') %>
+```
+
+In a controller:
+
+```ruby
+@onboarding_path = $pirate.ab_test(:new_onboarding, :control => '/onboarding', :welcome_flow => '/welcome') %>
+```
+
+You can call the feature multiple times with different variations:
 
 ```ruby
-$pirate.context(:user_id => current_user.id, :bot => false, :cookies => app_cookie_jar)
+@button_bg_color = $pirate.ab_test(:button_color, :control => "#FFF", :black => "#000")
+@button_text_color = $pirate.ab_test(:button_color, :control => "#CCC", :black => "#FFF")
 ```
 
-To establish identity, a context must have a user_id or a cookie_jar where blackbeard will cookie a visitor with it's own uid.  As cookie_jar is optional, you can collect metrics outside a web request.  You can also increment metrics for users other than the one currently logged in.  For example, if user A refers visitor B and vistor B joins, then you can increment User A's referrals.
+The best things to test are the biggest things that don't fit into a hash of options:
 
-It gets pretty tedious for a web app to constantly set the context. To make that more paletable you can use a before filter in Rails (or your framework's equivalent) and the $pirate.set_context method.
+```erb
+<% if $pirate.ab_test(:join_form) == :long_version do %>
+  <!-- extra field here -->
+<% end %>
+```
 
 ```ruby
-before_action do |controller|
-  $pirate.set_context(
-    :user_id => controller.current_user.id,
-    :bot => controller.bot?,
-    :cookies => controller.cookies)
+if $pirate.ab_test(:join_form) == :long_version do
+  # validate the extra fields
 end
 ```
 
-If you `set_context` you can now make calls directly on $pirate and they will be delegate to that context.
+If you're simply rolling out a feature or want a feature flipper, you can:
+
+```ruby
+if $pirate.active?(:friend_feed){ ... }  # shorthand for test(:friend_feed) == :active
+```
+
+GOTCHA #1:  It's good to avoid elsif and case statements when testing for features. Blackbeard learns about the features and their variations dynamically. If you're not passing in your variations as a hash, but only using conditionals, you can ensure all your variations are available with:
+
+```ruby
+$pirate.test(:friend_feed).add_variations(:variation_one, :variation_two, ...)
+```
+
+Look at the dashboard to see which variations are registered.
+
+Features do not turn on automatically. When you first deploy the feature will be set to `:inactive` or `:control`, `:off`, or `:default` if any of those variations are defined.
+
+GOTCHA #2:  If you do not define the :inactive, :control, :off or :default variations, the result will be nil. This is the desired behavior but it may be confusing.
 
 ```ruby
-$pirate.add_total(:like, +1)
+$pirate.ab_test(:new_onboarding, :one => 'one', :two => 'two') # is the same as the next line
+$pirate.ab_test(:new_onboarding, :inactive => nil, :one => 'one', :two => 'two') # nil when feature is inactive
+$pirate.ab_test(:new_onboarding, :default => 'one', :two => 'two') # => 'one' when feature is inactive
 ```
 
+### Defining groups
+
+```ruby
+$pirate.define_group(:admin) do |user, context|
+  user.admin? # true, false
+end
+
+$pirate.define_group(:medalist) do |user, context|
+  user.engagement_level # nil, :bronze, :silver, :gold
+end
+
+$pirate.define_group(:seo_traffic) do |user, context|
+  context.session.refer =~ /google.com/ # remember to store refer in sessions
+end
+
+$pirate.define_group(:seo_traffic) do |user, context|
+  context.session.refer =~ /google.com/ # remember to store refer in sessions
+end
+
+$pirate.define_group(:purchasers) do |user, context|
+  user.purchases.any?
+end
+```
 
 ## Contributing
 

data/Rakefile

@@ -1 +1,7 @@
+#!/usr/bin/env rake
 require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new('spec')
+
+task :default => :spec

data/TODO.md

@@ -16,6 +16,16 @@
       * by defined segments (e.g. staff?)
       * by user_id (e.g. rollout like)
 
+### Documentation
+
+### API and javascript $pirate
+
+### Funnels - collection of metrics
+
+hour: hash each "uid->from->to" => segment
+day: hash each "segment->from->to" => count
+week: hash each "segment->from->to" => count
+
 
 Create and manage multiple experiments in a browser/rack dashboard
 
@@ -37,41 +47,10 @@ $pirate.experiment(
 $pirate.funnel(:checkout, 'Confirm')          # User reached step 3 of funnel (Confirm)
 ```
 
-### Segments
-
-```ruby
-$pirate.segment(:premium_member) do
-  current_user.premium_member?  # true or false
-end
-
-$pirate.segment(:organization_size) do
-  current_user.organization_size # '0-5', '6-14', '15+'
-end
-```
-
-### Changes
-
-```ruby
-$pirate.change(:link, :control => 'blue', :red => 'red')
-$pirate.change(:link,
-  :control => nil, # noop
-  :red => Proc.new("red")
-)
-
 
-$pirate.variation(:link, :control) do
-  something.blue
+$pirate.define_group(:achieve_pirate_style) do |user, context|
+  $pirate.metric(:pirate_style).achieved?
 end
 
-$pirate.variation(:link, :red) do
-  ...
-end
-```
-
-### Outside a Web Session
 
-You can run them in crons or asynchronously.
-
-```ruby
-$pirate.context().goal(...)
-$pirate.context()
+http://blog.sourcing.io/structuring-sinatra?utm_content=buffer1955d&utm_medium=social&utm_source=twitter.com&utm_campaign=buffer

data/blackbeard.gemspec

@@ -20,10 +20,14 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency "bundler", "~> 1.3"
   spec.add_development_dependency "rake", "~> 10.0"
-  spec.add_development_dependency "rspec", "~> 2.6"
+  spec.add_development_dependency "rspec", "~> 2.14.1"
   spec.add_development_dependency 'rack-test', '~> 0.6'
+  spec.add_development_dependency 'guard-rspec', '~> 4.2.5'
+  spec.add_development_dependency 'terminal-notifier-guard'
+  spec.add_development_dependency 'codeclimate-test-reporter'
 
   spec.add_runtime_dependency "sinatra-base", "~> 1.4"
+  spec.add_runtime_dependency "sinatra-partial", "~> 0.4.0"
   spec.add_runtime_dependency "tzinfo", "~> 0.3"
   spec.add_runtime_dependency 'redis', '~> 3.0', '>= 3.0.4'
   spec.add_runtime_dependency 'redis-namespace', '~> 1.4', '>= 1.4.1'

data/console.rb

@@ -0,0 +1,3 @@
+$LOAD_PATH.unshift(File.expand_path('../lib', __FILE__))
+require 'blackbeard'
+