togls 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 29cf1b0568aea63a9f302b01727e2b03e2f6b022
-  data.tar.gz: 7b109336122ffd30f15621b8b769d3ad0556bd34
+  metadata.gz: f956666596995d557aa56048b785db8f490f73dc
+  data.tar.gz: ffa83b7c726ef586d20c169c6cf3d3189ee8207c
 SHA512:
-  metadata.gz: 76ed9cf6f4d3b726902a8332fb16b57a1f4355cd3004cf0eca1f73228a9e4c304a89c967ebf157ebe5b3cc5003809223ed5dfd2577eb78dbc9197d4567bd7f05
-  data.tar.gz: 466bb270590c5a5000340ce3585da8f51195ae9016f79b1200d09dcc2f2f620a3809ac4168b1f1b9b51f1dff6ca6f5911b15e4a3e4fd5303d0e35742db4357c9
+  metadata.gz: 50b448deb27e15b7815cafa0e02d366a01643038ca1a689695547e48234f0a2aafe5161cea5a9c9461d7b179022dd2cd22d8b8080756f3c62d760220a92e20f9
+  data.tar.gz: 00963574a1dbef269a279ae8b42294a11042a194f80b366f38b9136a5d23e4eba23a634d16705b1f8990ad9c4f56821db4bb754b8d3d05aba9ded8d8da6ba6a9

data/.gitignore

@@ -7,3 +7,4 @@
 /pkg/
 /spec/reports/
 /tmp/
+*.gem

data/ChangeLog.md

@@ -6,6 +6,12 @@ versions, as well as provide a rough history.
 
 #### Next Release
 
+#### v1.0.0
+
+* Require human readable description to define a feature toggle
+* Add rake task that outputs all the feature toggles states (on, off, ? -
+  unknown due to Compex Rule), keys, and human readable descritpions
+
 #### v0.1.0
 
 * Add concept of Groups as a provided rule

data/README.md

@@ -1,3 +1,4 @@
+[![Version](https://img.shields.io/gem/v/togls.svg)](https://rubygems.org/gems/togls)
 [![Build Status](https://travis-ci.org/codebreakdown/togls.svg?branch=master)](https://travis-ci.org/codebreakdown/togls)
 [![Code Climate](https://img.shields.io/codeclimate/github/codebreakdown/togls.svg)](https://codeclimate.com/github/codebreakdown/togls)
 [![Code
@@ -24,35 +25,150 @@ Or install it yourself as:
 
     $ gem install togls
 
-## Usage
+## Basic Usage
 
-### Setup
+The basic usage of `Togls` is outlined below.
 
-The default behaviour for any feature that has not been defined that is accessed is to default to false.
+### Defining Feature Toggles
+
+The first thing to do to use `Togls` is to define your feature toggles. The
+following is an example of how you might define your feature toggles. It is
+recommended this live in its own file. In Rails projects we recommend putting
+it in `config/initializers/togls_features.rb`.
 
 ```ruby
 Togls.features do
   # Set this feature to always be on
-  feature(:pop_up_login_form).on 
+  feature(:pop_up_login_form, "use the pop up login instead of normal login").on 
   # Set this feature to always be off
-  feature(:send_follup_email).off
+  feature(:send_follup_email, "send the follow up email").off
   # Create a group rule
   rule = Togls::Rules::Group.new(["user@email.com"])
-  feature(:new_contact_form).on(rule)
+  feature(:new_contact_form, "use new contact form instead of old one").on(rule)
 end
 ```
 
-### Evaluate
+### Evaluating Feature Toggles
+
+Once you have defined your feature toggles. The next thing you would likely
+want to do is conditionally control something based on them. The following are
+a few examples of how you would do this given the above.
 
 ```ruby
+if Togls.feature(:pop_up_login_form).on?
+  # Use pop up login form
+else
+  # Use normal non-pop up login form
+end
+
+if Togls.feature(:send_follup_email).on?
+  # send the follow up email
+end
+
 if Togls.feature(:new_contact_form).on?("user@email.com")
-  # Do my awesome feature
+  # Use new contact form
+else
+  # Use old contact form
+end
+```
+
+**Note:** The default behaviour for any feature that has not been defined that
+is accessed is to default to false.
+
+### Output Feature Toggles
+
+One other use case that we support as part of the *Basic Usage* is outputing all
+of the features in your system and their respective, **states** (`on`, `off`, `?` -
+unkown due to *Complex Rule*), **key**, and **human readable descrption**.
+
+We provide this functionality via a [rake](https://github.com/ruby/rake) task.
+
+#### Load rake task
+
+To use it you must first load the provided
+[rake](https://github.com/ruby/rake) file. This can be done in a number of
+different ways.
+
+##### Load rake task in another gem
+
+To use it in another gem you can use the following in the second gem's
+`Rakefile`.
+
+```ruby
+spec = Gem::Specification.find_by_name 'togls'
+load "#{spec.gem_dir}/lib/tasks/togls.rake"
+```
+
+**Note:** The features must be defined and loaded before calling this task or
+it will error out informing you that you need to define your features first.
+
+##### Load rake task in a Rails app
+
+To use the it in a Rails app you can do so by adding the following to the
+`Rakefile`.
+
+```ruby
+namespace :togls do
+  task :features => [:environment] do
+  end
 end
+
+spec = Gem::Specification.find_by_name 'togls'
+load "#{spec.gem_dir}/lib/tasks/togls.rake"
+```
+
+**Note:** The first hunk where it defines an empty `togls:features` tasks is
+important in Rails because it takes advantage of
+[rake](https://github.com/ruby/rake) task stacking and calls out the Rails
+environment as a dependency. That way before the `togls:feature` task is
+executed the `config/initializers/togls_features.rb` file is loaded which
+defines the feature toggles.
+
+#### Verify rake task loaded
+
+To verify that the rake task is loaded you can run `rake -T` and you should
+see something similar to the following in the output.
+
+```text
+rake togls:features                     # Output all features including status (on, off, ? - unknown due to complex rule), ke...
+```
+
+#### Run the rake task
+
+Once you have verified the task is loaded and available you can run it as
+follows.
+
+```shell
+rake togls:features
 ```
 
+The following is an example of what the output might look like if you defined
+a few test features.
+
+```text
+ on - :test1 - test 1 feature
+off - :test2 - test 2 feature
+off - :test3 - test 3 feature
+```
+
+## Advanced Usage
+
+Below is a breakdown of some of the more advanced features of `Togls` which
+aren't necessary in order to use it for basic feature toggles.
+
 ### Custom Rules
 
-A simple rule can be defined by created a rule object and passing a block
+`Togls` is specifically architected on top of a generic concept of a
+`Togls::Rule`.  This empowers the users to define any custom rules they would
+like and use them to control their feature toggles.  For example, you could
+use them to do A/B testing, define alpha test group, give a percentage of a
+user base a feature, etc.
+
+### Simple Rules
+
+A simple rule can be defined by creating a rule object and passing a block. In
+the following example any feature using the `gmail_rule` would only be on if
+the given `target` contained `gmail.com` at the end of the `target`.
 
 ```ruby
 # Only allow users with email addresses at gmail.com
@@ -63,7 +179,40 @@ Togls.features do
 end
 ```
 
-To implement a more complex rule a new rule object can be defined under Togls::Rules that implements the run method and returns a boolean. When a feature is defined, the rule will be added to the feature object and the run method called with whatever target is passed.
+### Complex Rules
+
+To implement a more complex rule, a new rule object can be defined under
+`Togls::Rules` that abides by the following.
+
+- inherits from `Togls::Rule` or a decendent of it
+- has an instance method named `run` that takes either a default value
+  parameter of `target` or a required paramter of `target`.
+
+    ```ruby
+    def run(target = 'foo')
+    ...
+    end
+    
+    # or
+
+    def run(target)
+    ...
+    end
+    ```
+
+- has the instance method named `run` return a boolean value identifying if
+  that feature should be on(`true`)/off(`false`) given the `target`.
+
+Thats it!
+
+#### Example Complex Rule
+
+Internally `Togls` uses these *Complex Rules* to provide functionality and
+will evolve to contain more official rules over time. If you have a generic
+*Complex Rule* you think should be part of `Togls` please make a pull request.
+
+A prime example of a *Complex Rule* provided by `Togls` is the
+`Togls::Rules::Group` rule. You can see it below.
 
 ```ruby
 module Togls
@@ -81,6 +230,25 @@ module Togls
 end
 ```
 
+Lets take a closer look at exactly what is going on here.
+
+- it is inheriting from the `Togls::Rule` class which meets one of the minimum
+  requirements for a rule.
+- its defines constructor takes an array identifiers and stores them. These
+  identifiers could be id numbers, email address, etc. **Note:** This
+  constructor is completely different than that of `Togls::Rule`. This
+  is fine because it is **not** a requirements that the constructor match.
+- its `run` method returns a boolean value identifying if the feature should
+  be on(`true`)/off(`false`) for the given `target`. It does so by identifying
+  if the array passed in at construction time `include?` the given `target`.
+  This meets one of the minimum requirement for a rule.
+- its `run` method signature requires a `target`. This meets a minimum
+  requirement for a rule as well. It also makes sense in the case of group
+  based rule as it has to have something to compare against the group.
+
+*Complex Rules* are a simple yet extremely power concept that you shouldn't
+hesitate to use.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/tasks/togls.rake

@@ -0,0 +1,8 @@
+namespace :togls do
+  desc "Output all features including status (on, off, ? - unknown due to complex rule), key, description"
+  task :features do
+    Togls.features.each do |key, feature|
+      puts feature.to_s
+    end
+  end
+end

data/lib/togls/errors.rb

@@ -0,0 +1,3 @@
+module Togls
+  class NoFeaturesError < StandardError; end
+end

data/lib/togls/feature.rb

@@ -1,25 +1,38 @@
 module Togls
   class Feature
-    attr_reader :key
+    attr_reader :key, :description
 
-    def initialize(key)
+    def initialize(key, description)
       @key = key
+      @description = description
       off
     end
 
     def on(rule = nil)
       if rule.nil?
-        rule = Rule.new { true }
+        rule = Togls::Rules::Boolean.new(true)
       end
       @rule = rule 
+      self
     end
 
     def off
-      @rule = Rule.new { false }
+      @rule = Togls::Rules::Boolean.new(false)
+      self
     end
 
     def on?(target = nil)
       @rule.run(target)
     end
+
+    def to_s
+      if @rule.is_a?(Togls::Rules::Boolean)
+        display_value = @rule.run ? ' on' : 'off'
+      else
+        display_value = '  ?'
+      end
+
+      "#{display_value} - #{@key.inspect} - #{@description}"
+    end
   end
 end

data/lib/togls/feature_registry.rb

@@ -2,7 +2,7 @@ module Togls
   class FeatureRegistry
     def initialize
       @registry = {}
-      @default_feature = Feature.new(:default).tap {|f| f.on(Rule.new { false }) }
+      @default_feature = Feature.new(:default, "the official default feature").tap {|f| f.on(Rule.new { false }) }
     end
 
     def self.create(&features)
@@ -11,8 +11,8 @@ module Togls
       registry
     end
 
-    def feature(tag)
-      @registry[tag.to_sym] = Feature.new(tag.to_sym)
+    def feature(tag, desc)
+      @registry[tag.to_sym] = Feature.new(tag.to_sym, desc)
     end
 
     def get(key)
@@ -21,5 +21,9 @@ module Togls
         @default_feature
       end
     end
+
+    def registry
+      @registry
+    end
   end
 end

data/lib/togls/rules/boolean.rb

@@ -0,0 +1,13 @@
+module Togls
+  module Rules
+    class Boolean < Rule
+      def initialize(bool)
+        @bool = bool
+      end
+
+      def run(target = nil)
+        return @bool
+      end
+    end
+  end
+end

data/lib/togls/rules.rb

@@ -1,3 +1,4 @@
+require 'togls/rules/boolean'
 require 'togls/rules/group'
 
 module Togls

data/lib/togls/version.rb

@@ -1,3 +1,3 @@
 module Togls
-  VERSION = "0.1.0"
+  VERSION = "1.0.0"
 end

data/lib/togls.rb

@@ -1,4 +1,5 @@
 require "togls/version"
+require "togls/errors"
 require "togls/feature_registry"
 require "togls/feature"
 require "togls/rule"
@@ -7,7 +8,15 @@ require "logger"
 
 module Togls
   def self.features(&features)
-    @feature_registry = FeatureRegistry.create(&features)
+    if !features.nil?
+      @feature_registry = FeatureRegistry.create(&features)
+    else
+      if @feature_registry.nil?
+        raise Togls::NoFeaturesError, "Need to define features before you can get them"
+      else
+        @feature_registry.registry
+      end
+    end
   end
   
   def self.feature(key)

data/togls.gemspec

@@ -19,7 +19,7 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 1.8"
+  spec.add_development_dependency "bundler", "~> 1.9"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec", "~> 3.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: togls
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Brian Miller
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-05-03 00:00:00.000000000 Z
+date: 2015-05-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -17,14 +17,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.8'
+        version: '1.9'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.8'
+        version: '1.9'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -75,11 +75,14 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- lib/tasks/togls.rake
 - lib/togls.rb
+- lib/togls/errors.rb
 - lib/togls/feature.rb
 - lib/togls/feature_registry.rb
 - lib/togls/rule.rb
 - lib/togls/rules.rb
+- lib/togls/rules/boolean.rb
 - lib/togls/rules/group.rb
 - lib/togls/version.rb
 - togls.gemspec