feature_flipper 1.0.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Florian Munz
+
+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.md

@@ -0,0 +1,118 @@
+FeatureFlipper
+==============
+
+FeatureFlipper is a simple library that allows you to restrict certain blocks
+of code to certain environments. This is mainly useful in projects where
+you deploy your application from HEAD and don't use branches.
+
+Install
+-------
+
+FeatureFlipper is packaged as a gem:
+
+    $ gem install feature_flipper
+
+In your project you have to configure the path to the app specific
+configuration file after requiring FeatureFlipper:
+
+    require 'feature_flipper'
+    FeatureFlipper::Config.path_to_file = "#{RAILS_ROOT}/config/features.rb"
+
+Configuration
+-------------
+
+You need to create a configuration file which defines the two entities
+FeatureFlipper cares about:
+
+ * states
+ * features
+
+You first define multiple 'states' which normally depend on an environment
+(for example: the state 'dev' is only active on development boxes). After that
+you add 'features' which correspond to logical chunks of work in your project.
+These features then move through the different states as they get developed.
+
+### Defining features
+
+A feature needs to have a name and you can add additional information like a
+more detailed description, a ticket number, a date when it was started, etc.
+Features are always defined in a state, you cannot define a feature which
+doesn't belong to a state.
+
+    in_status :dev do
+      feature :rating_game, :description => 'play a game to get recommendations'
+    end
+
+### Defining states
+
+A state is just a name and a boolean check. The check needs to evaluate to
+´true´ when it is active. For a Rails app you can just use environments:
+
+    :dev      => ['development', 'test'].include?(Rails.env),
+
+Usage
+-----
+
+In your code you then use the `show_feature?` method to branch depending on
+wether the feature is active or not:
+
+    if show_feature?(:rating_game)
+      # new code
+    else
+      # old code
+    end
+
+The `show_feature?` method is defined on Object, so you can use it everywhere.
+
+Example config file
+-------------------
+
+    FeatureFlipper.features do
+      in_status :dev do
+        feature :rating_game, :description => 'play a game to get recommendations'
+      end
+
+      in_status :live do
+        feature :city_feed, :description => 'stream of content for each city'
+      end
+    end
+
+    FeatureFlipper::Config.states = {
+      :dev      => ['development', 'test'].include?(Rails.env),
+      :live     => true
+    }
+
+This is your complete features.rb config file. In the example there are two
+states: `:dev` is active on development boxes and `:live` is always active
+(this is the last state a feature is in).
+
+The feature `:rating_game` is still in development and not shown on the
+production site. The feature `:city_feed` is done and already enabled
+everywhere. You transition features between states by just moving the line to
+the new state block.
+
+You can take a look at this example in detail in the 'examples' folder.
+
+Cleaning up
+-----------
+
+The drawback of this approach is that your code can get quite ugly with all
+these if/else branches. So you have to be strict about removing (we call it
+de-featurizing) features after they have gone live.
+
+Meta
+----
+
+* Code: `git clone git://github.com/qype/feature_flipper.git`
+* Home: <http://github.com/qype/feature_flipper>
+* Bugs: <http://github.com/qype/feature_flipper/issues>
+
+This project uses [Semantic Versioning][sv].
+
+Author
+------
+
+Florian Munz, Qype GmbH - florian@qype.com
+
+
+[sv]: http://semver.org/

data/Rakefile

@@ -0,0 +1,21 @@
+require 'rake'
+require 'rake/testtask'
+
+desc 'Default: run unit tests'
+task :default => :test
+
+desc 'run the feature_flipper tests'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+begin
+  require 'mg'
+  MG.new('feature_flipper.gemspec')
+rescue LoadError
+  warn 'mg not available.'
+  warn 'Install it with: gem install mg'
+end

data/examples/features.rb

@@ -0,0 +1,19 @@
+#
+# This is an example configuration file. It defines two states and
+# two features.
+#
+
+FeatureFlipper.features do
+  in_status :dev do
+    feature :rating_game, :description => 'play a game to get recommendations'
+  end
+
+  in_status :live do
+    feature :city_feed, :description => 'stream of content for each city'
+  end
+end
+
+FeatureFlipper::Config.states = {
+  :dev      => ['development', 'test'].include?(Rails.env),
+  :live     => true
+}

data/examples/simple.rb

@@ -0,0 +1,39 @@
+# Setup
+#
+
+# just need this to make it work from within the library
+$LOAD_PATH.unshift File.dirname(__FILE__) + '/../lib'
+
+# fake production Rails environment
+module Rails
+  def self.env
+    'production'
+  end
+end
+
+
+# Configuration
+#
+
+require 'feature_flipper'
+
+# set the path to your app specific config file
+FeatureFlipper::Config.path_to_file = "features.rb"
+
+
+# Usage
+#
+
+# rating_game is still in development, so shouldn't be shown on production
+if show_feature?(:rating_game)
+  puts "Rating Game"
+else
+  puts "old stuff"
+end
+
+# city_feed is enabled everywhere
+if show_feature?(:city_feed)
+  puts "City Feed"
+else
+  puts "old stuff"
+end

data/lib/feature_flipper/config.rb

@@ -0,0 +1,97 @@
+module FeatureFlipper
+  module Config
+    @features = {}
+    @states   = {}
+
+    def self.path_to_file
+      @path_to_file || File.join(Rails.root, 'config', 'features.rb')
+    end
+
+    def self.path_to_file=(path_to_file)
+      @path_to_file = path_to_file
+    end
+
+    def self.ensure_config_is_loaded
+      return if @config_loaded
+
+      load path_to_file
+      @config_loaded = true
+    end
+
+    def self.reload_config
+      @config_loaded = false
+    end
+
+    def self.features
+      @features
+    end
+
+    def self.features=(features)
+      @features = features
+    end
+
+    def self.states
+      @states
+    end
+
+    def self.states=(states)
+      @states = states
+    end
+
+    def self.get_status(feature_name)
+      feature = features[feature_name]
+      feature ? feature[:status] : nil
+    end
+
+    def self.active_status?(status)
+      active = states[status]
+      if active.is_a?(Hash)
+        group, group_status = active.to_a.flatten
+        FeatureFlipper.current_feature_group == group || states[group_status] == true
+      else
+        active == true
+      end
+    end
+
+    def self.is_active?(feature_name)
+      ensure_config_is_loaded
+
+      status = get_status(feature_name)
+      if status.is_a?(Symbol)
+        active_status?(status)
+      elsif status.is_a?(Proc)
+        status.call == true
+      else
+        status == true
+      end
+    end
+  end
+
+  class Mapper
+    def initialize(status)
+      @status = status
+    end
+
+    def feature(name, options = {})
+      FeatureFlipper::Config.features[name] = options.merge(:status => @status)
+    end
+  end
+
+  class StatusMapper
+    def in_status(status, &block)
+      Mapper.new(status).instance_eval(&block)
+    end
+  end
+
+  def self.features(&block)
+    StatusMapper.new.instance_eval(&block)
+  end
+
+  def self.current_feature_group
+    Thread.current[:feature_system_current_feature_group]
+  end
+
+  def self.current_feature_group=(feature_group)
+    Thread.current[:feature_system_current_feature_group] = feature_group
+  end
+end

data/lib/feature_flipper/show.rb

@@ -0,0 +1,13 @@
+module FeatureFlipper
+  module Show
+    extend self
+
+    def self.included(base)
+      base.extend(self)
+    end
+
+    def show_feature?(feature_name)
+      FeatureFlipper::Config.is_active?(feature_name)
+    end
+  end
+end

data/lib/feature_flipper/version.rb

@@ -0,0 +1,3 @@
+module FeatureFlipper
+  Version = VERSION = '1.0.0'
+end

data/lib/feature_flipper.rb

@@ -0,0 +1,5 @@
+require 'feature_flipper/show'
+require 'feature_flipper/config'
+
+# we need the show_feature? method everywhere
+Object.send(:include, FeatureFlipper::Show)

data/test/feature_flipper_test.rb

@@ -0,0 +1,94 @@
+require 'test_helper'
+
+context 'hash based FeatureFlipper' do
+  setup do
+    FeatureFlipper::Config.path_to_file = 'features.rb'
+    FeatureFlipper::Config.reload_config
+  end
+
+  test 'should show enabled features' do
+    assert show_feature?(:live_feature)
+  end
+
+  test 'should not show disabled features' do
+    assert !show_feature?(:disabled_feature)
+  end
+
+  test 'should not show a feature when on a higher environment' do
+    Rails.stubs(:env).returns('production')
+    assert !show_feature?(:dev_feature)
+  end
+
+  test 'show feature should work with booleans' do
+    assert show_feature?(:boolean_feature)
+  end
+
+  test 'show feature should work with procs' do
+    assert show_feature?(:proc_feature)
+  end
+
+  test 'should show a beta feature to the feature group' do
+    Rails.stubs(:env).returns('production')
+    FeatureFlipper.stubs(:current_feature_group).returns(:beta_users)
+
+    assert show_feature?(:beta_feature)
+  end
+
+  test 'should not show a beta feature if not in the group' do
+    Rails.stubs(:env).returns('production')
+    FeatureFlipper.stubs(:current_feature_group).returns(nil)
+
+    assert !show_feature?(:beta_feature)
+  end
+
+  test 'should always show a beta feature on dev' do
+    Rails.stubs(:env).returns('development')
+    FeatureFlipper.stubs(:current_feature_group).returns(nil)
+
+    assert show_feature?(:beta_feature)
+  end
+
+  test 'should be able to get features' do
+    FeatureFlipper::Config.ensure_config_is_loaded
+    all_features = FeatureFlipper::Config.features
+
+    assert_not_nil all_features
+    assert all_features.is_a?(Hash)
+    assert_equal :dev, all_features[:dev_feature][:status]
+    assert_equal 'dev feature', all_features[:dev_feature][:description]
+  end
+end
+
+context 'DSL based FeatureFlipper' do
+  setup do
+    FeatureFlipper::Config.path_to_file = 'features_dsl.rb'
+    FeatureFlipper::Config.reload_config
+  end
+
+  test 'should show enabled features' do
+    assert show_feature?(:live_feature)
+  end
+
+  test 'should not show a feature when on a higher environment' do
+    Rails.stubs(:env).returns('production')
+    assert !show_feature?(:dev_feature)
+  end
+
+  test 'show feature should work with booleans' do
+    assert show_feature?(:boolean_feature)
+  end
+
+  test 'show feature should work with procs' do
+    assert show_feature?(:proc_feature)
+  end
+
+  test 'should be able to get features' do
+    FeatureFlipper::Config.ensure_config_is_loaded
+    all_features = FeatureFlipper::Config.features
+
+    assert_not_nil all_features
+    assert all_features.is_a?(Hash)
+    assert_equal :dev, all_features[:dev_feature][:status]
+    assert_equal 'dev feature', all_features[:dev_feature][:description]
+  end
+end

data/test/features.rb

@@ -0,0 +1,16 @@
+FeatureFlipper::Config.features = {
+  :live_feature     => { :status => :live },
+  :disabled_feature => { :status => :disabled },
+  :dev_feature      => { :status => :dev, :description => 'dev feature' },
+  :boolean_feature  => { :status => true },
+  :proc_feature     => { :status => Proc.new { Date.today > Date.today - 84000 } },
+  :beta_feature     => { :status => :beta }
+}
+
+
+FeatureFlipper::Config.states = {
+  :disabled => false,
+  :dev      => ['development', 'test'].include?(Rails.env),
+  :beta     => { :beta_users => :dev },
+  :live     => true
+}

data/test/features_dsl.rb

@@ -0,0 +1,23 @@
+FeatureFlipper.features do
+  in_status :dev do
+    feature :dev_feature, :description => 'dev feature'
+  end
+
+  in_status :live do
+    feature :live_feature
+  end
+
+  in_status true do
+    feature :boolean_feature
+  end
+
+  in_status Proc.new { Date.today > Date.today - 84000 } do
+    feature :proc_feature
+  end
+end
+
+
+FeatureFlipper::Config.states = {
+  :dev      => ['development', 'test'].include?(Rails.env),
+  :live     => true
+}

data/test/test_helper.rb

@@ -0,0 +1,38 @@
+require 'test/unit'
+require 'rubygems'
+
+require 'mocha'
+
+##
+# test/spec/mini 5
+# http://gist.github.com/307649
+# chris@ozmm.org
+#
+def context(*args, &block)
+  return super unless (name = args.first) && block
+  require 'test/unit'
+  klass = Class.new(defined?(ActiveSupport::TestCase) ? ActiveSupport::TestCase : Test::Unit::TestCase) do
+    def self.test(name, &block)
+      define_method("test_#{name.to_s.gsub(/\W/,'_')}", &block) if block
+    end
+    def self.xtest(*args) end
+    def self.context(*args, &block) instance_eval(&block) end
+    def self.setup(&block)
+      define_method(:setup) { self.class.setups.each { |s| instance_eval(&s) } }
+      setups << block
+    end
+    def self.setups; @setups ||= [] end
+    def self.teardown(&block) define_method(:teardown, &block) end
+  end
+  (class << klass; self end).send(:define_method, :name) { name.gsub(/\W/,'_') }
+  klass.class_eval &block
+end
+
+
+module Rails
+  def self.env
+    'test'
+  end
+end
+
+require 'feature_flipper'

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification 
+name: feature_flipper
+version: !ruby/object:Gem::Version 
+  version: 1.0.0
+platform: ruby
+authors: 
+- Florian Munz
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-05-07 00:00:00 +02:00
+default_executable: 
+dependencies: []
+
+description: |
+  FeatureFlipper is a simple library that allows you to restrict certain blocks
+  of code to certain environments. This is mainly useful in projects where
+  you deploy your application from HEAD and don't use branches.
+
+email: florian@qype.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README.md
+- Rakefile
+- LICENSE
+- lib/feature_flipper/config.rb
+- lib/feature_flipper/show.rb
+- lib/feature_flipper/version.rb
+- lib/feature_flipper.rb
+- test/feature_flipper_test.rb
+- test/features.rb
+- test/features_dsl.rb
+- test/test_helper.rb
+- examples/features.rb
+- examples/simple.rb
+has_rdoc: true
+homepage: http://github.com/qype/feature_flipper
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: FeatureFlipper helps you flipping features
+test_files: []
+