fluidfeatures-rails 0.4.4 → 0.5.0

data/README.md

@@ -1,6 +1,177 @@
+[![Build Status](https://secure.travis-ci.org/FluidFeatures/fluidfeatures-rails.png)](http://travis-ci.org/FluidFeatures/fluidfeatures-rails)
 
-fluidfeatures-rails
-===================
+Rails graceful feature rollout and simple A/B testing
+=====================================================
+
+`gem fluidfeatures-rails` is a Ruby on Rails client for the API of FluidFeatures.com, which provides an elegant way to wrap new code so you have real-time control over rolling out new features to your user-base.
+
+Rollout new versions of features
+--------------------------------
+
+Using `if ff? "foo"` you can easily rollout new code to production and then use the FluidFeatures dashboard to rollout this code to yourself, your team or your users.
+
+Use `if ff? "foo", "v2"` to wrap the code for a new version of the "foo" feature.
+
+`if ff? "foo"` defaults to version `"default"`, so anyone seeing "v2" will not also see "v2". This is a great way to test new features in production.
+
+Once you have moved all your users over to the newer "v2" version you can factor out code from the older version.
+
+Tracking goals
+--------------
+
+Sometimes referred to as "conversions", goals are a simple way of flagging that an condition has been met. You can do this in your Rails controllers with `fluidgoal(<goal-name>)`. A statement such as `fluidgoal "upgraded-to-pro-account"` tells FluidFeatures that your user upgraded their account.
+
+You can do this in controller, or in your view and you will immediately be able to see statistics within the FluidFeatures dashboard. Statistics show you will versions of which features play the greatest roll in driving your users towards these goals.
+
+A/B testing
+-----------
+
+By combining 2 versions of a feature and one goal (see above) you can start to easily perform A/B testing. FluidFeatures will keep track of which version is winning in terms of statistically hitting the goal more often.
+
+If you only roll out one of the versions to a small percentage, say 2%, of your user base, then this is taken into account when calculating the version success statistics. This means you can easily trial experimental features or new versions of existing features.
+
+Multi-variant testing and beyond
+--------------------------------
+
+While A/B testing might be enough for some, you have the power to do much more.
+
+You can define any number of versions for a feature and track them all.
+
+You can also compare the performance of different features against each other over time.
+
+On your server
+--------------
+
+A/B testing on the server gives you the ability to test things at all levels of your stack. Test alternate SQL statements, different versions of emails sent to users, or different backend 3rd party API services.
+
+In your templates
+-----------------
+
+fluidfeatures-rails exposes `def ff?` (alias to `def fluidfeature`) and `def fluidgoal` to your templates, so can also wrap versioned code there.
+
+User definition and cohorts
+---------------------------
+
+In your `application_controller.rb` you will define a function called `def fluidfeatures_current_user` which can be called by `gem fluidfeatures-rails` to determine who the current user is.
+
+This important for FluidFeatures to determine which feature versions to enable for the user, but is also the place where you can define any cohorts you wish to use for rolling out features.
+
+```ruby
+def fluidfeatures_current_user(verbose)
+  if current_user
+    if verbose
+      {
+        :id => @current_user[:id],
+        :name => @current_user[:name],
+        :uniques => {
+          :twitter => @current_user[:twitter_id]
+        },
+        :cohorts => {
+          # Example attributes for the user.
+          # These can be any fields you wish to select users by.
+          :company  => {
+            # "display" is used to help you find it in the dashboard.
+            # Highly recommended unless you work with ids.
+            # This display name can change over time without consequence. 
+            :display => @current_user[:company_name],
+            # "id" should be unique this this cohort and must be static
+            # over time.
+            :id      => @current_user[:company_id]
+          },
+          # For this boolean cohort "true"|"false" is the "display"
+          # and the "id"
+          :admin    => @current_user[:admin]
+        }
+      }
+    else
+      {
+        :id => @current_user.id
+      }
+    end
+  else
+    nil
+  end
+end
+```
+
+The above is an example of `fluidfeatures_current_user` that you might implement. The `verbose` is a boolean that indicates whether all details are required, or just the minimal identifying attributes (unique `:id`). `verbose` is an optimization that will be used at the discretion of `gem fluidfeatures-rails`.
+
+`:name` allows you to pass the human-readable string, such as `"John Doe"`, that represents the user. This is then used in the FluidFeatures dashboard for display and search purposes. You can very quickly search for this user and enable a new feature for them.
+
+`:uniques` are other unique attributes of the user that you can pass to FluidFeatures. For instance, their Twitter handle. These can also be used for search in the dashboard. FluidFeatures may use these for further integrate, such as displaying Twitter profile pictures.
+
+`:cohorts` are non-unique attributes of the user. You can define any attribute you wish. Common ones are `:admin` (`true` or `false`), but could be anything from the month when they joined (`:joined => "2011-04"`), to whether or not they drink coffee (`"coffee-drinker" => false`). Again, you can search on these attributes and enable specific versions of features based on these attributes.
+
+Anonymous users
+---------------
+
+If your `ApplicationController` method `fluidfeatures_current_user` returns `nil` fluidfeatures-rails assumes that your user is anonymous and it will set a cookie in the user's browser. The cookie enables FluidFeatures to provide a consistent experience for that anonymous user. This is mostly important when you have feature versions enabled on a percentage of random users, when two anonymous user may have different features shown to them, depending on which percentage they random fall into.
+
+It is possible handle anonymous users yourself by managing the cookies yourself, generating a unique `:id` for each anonymous user and additionally passing `:anonymous => true` in the `Hash` of `fluidfeatures_current_user` for both verbose and non-verbose calls. This basically what `gem fluidfeatures-rails` does under the hood for your convenience, so you do not have to.
+
+Integration
+-----------
+
+Add the gem to your application
+
+```ruby
+gem "fluidfeatures-rails"
+```
+
+Call the initializer when your application starts
+
+```ruby
+module MyRailsApp
+  class Application < Rails::Application
+    FluidFeatures::Rails.initializer
+  end
+end
+```
+
+Create a `fluidfeature_current_user` method in your `ApplicationController`. See [User definition and cohorts](#user-definition-and-cohorts).
+
+Start adding your features and goals using `if ff?` (or `if fluidfeature`) and `fluidgoal`.
+
+In your controllers or your views...
+
+```ruby
+# "theme" is simply an example feature name, used to represent
+# a migration to a styling of your website
+if ff? "theme", "default"
+  # wrap code related to your default theme, so it is
+  # only executed when the user is allocated this version
+  # of the feature "theme".
+end
+# Alternate verison of the "theme" feature.
+# FluidFeatures will only assign a user to one version
+# of a feature.
+if ff? "theme", "tropical"
+  # implement code specifically related to your new theme
+end
+
+fluidgoal "bought-bieber-dvd"
+
+fluidgoal "added-a-comment"
+
+fluidgoal "upgraded-to-pro-account"
+
+fluidgoal "general-engagement"
+```
+
+Dashboard
+---------
+
+If you log into your FluidFeatures account and visit [fluidfeatures.com/dashboard](https://www.fluidfeatures.com/dashboard) you will see your feature and goal dashboard.
+
+![Example dashboard view](http://commondatastorage.googleapis.com/philwhln/blog/images/ab-test-rails/full-dashboard.png)
+
+This shows one features `"ab-test"` with two versions simply named `"a"` and `"b"`.
+
+There are two goals called `"yes"` and `"no"`.
+
+Version `"a"` is seen by 75% of the user-base, whether they are anonymous or not, and version `"b"` is seen by the remaining 25%.
+
+You can read more about this example in a blog post here...
+http://www.bigfastblog.com/ab-testing-in-ruby-on-rails
 
-Rails client for API of FluidFeatures.com
 

data/fluidfeatures-rails.gemspec

@@ -15,7 +15,7 @@ Gem::Specification.new do |s|
   s.test_files    = `git ls-files -- {spec}/*`.split("\n")
   s.require_paths = ["lib"]
 
-  s.add_dependency "fluidfeatures", "~>0.4.4" unless ENV["FF_DEV"]
+  s.add_dependency "fluidfeatures", "~> 0.5.0" unless ENV["FF_DEV"]
 
   s.add_development_dependency('rake', '~> 10.0.2')
   s.add_development_dependency('rspec', '~> 2.12.0')

data/lib/fluidfeatures/rails.rb

@@ -1,4 +1,3 @@
-
 require "fluidfeatures"
 
 module FluidFeatures
@@ -20,12 +19,12 @@ module FluidFeatures
       # Without these FluidFeatures credentials we cannot talk to
       # the FluidFeatures service.
       #
-      %w[FLUIDFEATURES_BASEURI FLUIDFEATURES_SECRET FLUIDFEATURES_APPID].each do |key|
-        unless ENV[key]
-          $stderr.puts "!! fluidfeatures-rails requires ENV[\"#{key}\"] (fluidfeatures is disabled)"
-          return
-        end
-      end
+      #%w[FLUIDFEATURES_BASEURI FLUIDFEATURES_SECRET FLUIDFEATURES_APPID].each do |key|
+      #  unless ENV[key]
+      #    $stderr.puts "!! fluidfeatures-rails requires ENV[\"#{key}\"] (fluidfeatures is disabled)"
+      #    return
+      #  end
+      #end
       unless defined? ::Rails
         $stderr.puts "!! fluidfeatures-rails requires rails (fluidfeatures is disabled)"
         return
@@ -34,17 +33,12 @@ module FluidFeatures
 
       ::Rails::Application.initializer "fluidfeatures.initializer" do
         ActiveSupport.on_load(:action_controller) do
-          api_baseuri = ENV["FLUIDFEATURES_BASEURI"]
-          api_appid   = ENV["FLUIDFEATURES_APPID"]
-          api_secret  = ENV["FLUIDFEATURES_SECRET"]
-
-          ::FluidFeatures::Rails.ff_app = ::FluidFeatures.app(
-            api_baseuri,
-            api_appid,
-            api_secret,
-            #::Rails.logger
-          )
-
+          replacements = {}
+          replacements["baseuri"] = ENV["FLUIDFEATURES_BASEURI"] if ENV["FLUIDFEATURES_BASEURI"]
+          replacements["appid"] = ENV["FLUIDFEATURES_APPID"] if ENV["FLUIDFEATURES_APPID"]
+          replacements["secret"] = ENV["FLUIDFEATURES_SECRET"] if ENV["FLUIDFEATURES_SECRET"]
+          config = ::FluidFeatures::Config.new("#{::Rails.root}/config/stormpath.yml", ::Rails.env, replacements)
+          ::FluidFeatures::Rails.ff_app = ::FluidFeatures.app(config)
           ActionController::Base.append_before_filter :fluidfeatures_request_before
           ActionController::Base.append_after_filter  :fluidfeatures_request_after
         end
@@ -62,7 +56,9 @@ module ActionController
     attr_accessor :ff_transaction
 
     # allow fluidfeature to be called from templates
+    helper_method :ff?
     helper_method :fluidfeature
+    helper_method :fluidgoal
 
     #
     # Here is how we know what your user_id is for the user

data/lib/fluidfeatures/rails/version.rb

@@ -1,5 +1,5 @@
 module FluidFeatures
   module Rails
-    VERSION = '0.4.4'
+    VERSION = '0.5.0'
   end
 end

data/lib/generators/fluidfeatures/rails/install/install_generator.rb

@@ -0,0 +1,29 @@
+module FluidFeatures
+  module Rails
+    module Generators
+      class InstallGenerator < ::Rails::Generators::Base
+        def create_initializer_file
+          create_file "config/fluidfeatures.yml", "common:
+  baseuri: https://www.fluidfeatures.com/service
+  cache:
+    enable: false
+    dir: tmp/fluidfeatures
+    limit: 2mb
+
+development:
+  appid:
+  secret:
+
+test:
+  appid:
+  secret:
+
+production:
+  appid:
+  secret:
+"
+        end
+      end
+    end
+  end
+end

data/spec/generators/fluidfeatures/rails/install/install_generator_spec.rb

@@ -0,0 +1,9 @@
+require "spec_helper"
+require "generators/fluidfeatures/rails/install/install_generator"
+
+describe FluidFeatures::Rails::Generators::InstallGenerator do
+  it "creates a configuration file" do
+    subject.should_receive(:create_file).with("config/fluidfeatures.yml", kind_of(String))
+    subject.create_initializer_file
+  end
+end

data/spec/initializer_spec.rb

@@ -8,15 +8,6 @@ describe "FluidFeatures Rails initialization" do
     CONFIG_KEYS.each {|k| ENV[k] = k}
   end
 
-  CONFIG_KEYS.each do |key|
-    it "should require #{key} environment variable" do
-      ENV[key] = nil
-      $stderr.should_receive(:puts).with("!! fluidfeatures-rails requires ENV[\"#{key}\"] (fluidfeatures is disabled)")
-      FluidFeatures::Rails.initializer
-      FluidFeatures::Rails.enabled.should be_false
-    end
-  end
-
   it "should start application if Rails defined" do
     defined?(Rails).should be_true
     $stderr.should_receive(:puts).with("=> fluidfeatures-rails initializing as app #{ENV["FLUIDFEATURES_APPID"]} with #{ENV["FLUIDFEATURES_BASEURI"]}")
@@ -32,12 +23,20 @@ describe "FluidFeatures Rails initialization" do
       FluidFeatures.stub!(:app)
       ActionController::Base.stub!(:append_before_filter)
       ActionController::Base.stub!(:append_after_filter)
+      FluidFeatures::Config.stub(:new).and_return({})
+      Rails.stub!(:root).and_return(".")
+      Rails.stub!(:env).and_return(:development)
       FluidFeatures::Rails.initializer
     end
 
+    it "should create config" do
+      FluidFeatures::Config.should_receive(:new).and_return({})
+      instance_eval &on_load
+    end
+
     it "should create app with passed credentials" do
       @app = mock("app")
-      FluidFeatures.should_receive(:app).with(ENV["FLUIDFEATURES_BASEURI"], ENV["FLUIDFEATURES_APPID"], ENV["FLUIDFEATURES_SECRET"]).and_return(@app)
+      FluidFeatures.should_receive(:app).with({}).and_return(@app)
       instance_eval &on_load
       FluidFeatures::Rails.ff_app.should == @app
     end

data/spec/support/rails.rb

@@ -26,4 +26,9 @@ module Rails
   def self.logger
     @@logger ||= Object.new
   end
+
+  module Generators
+    class Base
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fluidfeatures-rails
 version: !ruby/object:Gem::Version
-  version: 0.4.4
+  version: 0.5.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-12-05 00:00:00.000000000 Z
+date: 2013-01-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: fluidfeatures
@@ -18,7 +18,7 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 0.4.4
+        version: 0.5.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -26,7 +26,7 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 0.4.4
+        version: 0.5.0
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -111,9 +111,11 @@ files:
 - lib/fluidfeatures/rails/app/controllers/fluidfeatures_controller.rb
 - lib/fluidfeatures/rails/config/routes.rb
 - lib/fluidfeatures/rails/version.rb
+- lib/generators/fluidfeatures/rails/install/install_generator.rb
 - lib/pre_ruby192/uri.rb
 - spec/controller_extentions_spec.rb
 - spec/controller_spec.rb
+- spec/generators/fluidfeatures/rails/install/install_generator_spec.rb
 - spec/initializer_spec.rb
 - spec/routes_spec.rb
 - spec/spec_helper.rb