scientist 1.1.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 5c22232b66f7eeb5a35e4f6a308042bdbed6a42b
-  data.tar.gz: 18765e089ded1443d66ece9a606bea76df53fc51
+SHA256:
+  metadata.gz: 2ad0ca94921ed85fa82b13057d4c68c842d42ea256df543b32196e665c75519c
+  data.tar.gz: 02f8948568c02e57d003b42a7ca4964e78e1ca14df57b6f204c2db31be5098a9
 SHA512:
-  metadata.gz: fe1306268ecef4790dc0acc9c9d8783c3ba4088d0bc7aabda95725cf805cbee06ac058cbbbd2783e5f785236e60288146091ac6794e2ba7b912c3695ac3415b4
-  data.tar.gz: 262e07ce96dee85a475c962ba3de7e5f2eafb3199ba036d7a6cd727693baf27271cef7f84b310bcaad1d187a98317edcc2aeee9026dae6b1dc8028b8b6aeecc3
+  metadata.gz: 671d170da1739b46f102a898a32b522438f45323cc1d2b788865566bfc2c16d16c6b364c4610a97ee30e4da597642bb4ad9d2c422384eddbab278ae170469f9f
+  data.tar.gz: 5334f5ae2d735cdc3b230bfefd469bd51c9e9363ec5cec83d45e99cbb2b3b55fa14f057dc59dc7909828dc0182c9168c9a86d47efe5529971206b9ff5c14a52a

data/README.md

@@ -394,6 +394,10 @@ Because `enabled?` and `run_if` determine when a candidate runs, it's impossible
 
 When using Scientist, we've found it most useful to modify both the existing and new systems simultaneously anywhere writes happen, and verify the results at read time with `science`. `raise_on_mismatches` has also been useful to ensure that the correct data was written during tests, and reviewing published mismatches has helped us find any situations we overlooked with our production data at runtime. When writing to and reading from two systems, it's also useful to write some data reconciliation scripts to verify and clean up production data alongside any running experiments.
 
+#### Noise and error rates
+
+Keep in mind that Scientist's `try` and `use` blocks run sequentially in random order. As such, any data upon which your code depends may change before the second block is invoked, potentially yielding a mismatch between the candidate and control return values. To calibrate your expectations with respect to [false negatives](https://en.wikipedia.org/wiki/Type_I_and_type_II_errors) arising from systemic conditions external to your proposed changes, consider starting with an experiment in which both the `try` and `use` blocks invoke the control method. Then proceed with introducing a candidate.
+
 ### Finishing an experiment
 
 As your candidate behavior converges on the controls, you'll start thinking about removing an experiment and using the new behavior.
@@ -458,6 +462,17 @@ science "various-ways", run: "first-way" do |e|
 end
 ```
 
+### Without including Scientist
+
+If you need to use Scientist in a place where you aren't able to include the Scientist module, you can call `Scientist.run`:
+
+```ruby
+Scientist.run "widget-permissions" do |e|
+  e.use { model.check_user(user).valid? }
+  e.try { user.can?(:read, model) }
+end
+```
+
 ## Hacking
 
 Be on a Unixy box. Make sure a modern Bundler is available. `script/test` runs the unit tests. All development dependencies are installed automatically. Science requires Ruby 1.9 or newer.
@@ -477,6 +492,8 @@ Be on a Unixy box. Make sure a modern Bundler is available. `script/test` runs t
 - [MadcapJake/Test-Lab](https://github.com/MadcapJake/Test-Lab) (Perl 6)
 - [cwbriones/scientist](https://github.com/cwbriones/scientist) (Elixir)
 - [calavera/go-scientist](https://github.com/calavera/go-scientist) (Go)
+- [jelmersnoeck/experiment](https://github.com/jelmersnoeck/experiment) (Go)
+- [spoptchev/scientist](https://github.com/spoptchev/scientist) (Kotlin / Java)
 
 
 ## Maintainers

data/lib/scientist.rb

@@ -3,6 +3,9 @@
 # defining and running experiments.
 #
 # If you need to run science on class methods, extend this module instead.
+#
+# If including or extending this module are not an option, call
+# `Scientist.run`.
 module Scientist
   # Define and run a science experiment.
   #
@@ -15,9 +18,8 @@ module Scientist
   #
   # Returns the calculated value of the control experiment, or raises if an
   # exception was raised.
-  def science(name, opts = {})
+  def self.run(name, opts = {})
     experiment = Experiment.new(name)
-    experiment.context(default_scientist_context)
 
     yield experiment
 
@@ -25,6 +27,26 @@ module Scientist
     experiment.run(test)
   end
 
+  # Define and run a science experiment.
+  #
+  # name - a String name for this experiment.
+  # opts - optional hash with the the named test to run instead of "control",
+  #        :run is the only valid key.
+  #
+  # Yields an object which implements the Scientist::Experiment interface.
+  # See `Scientist::Experiment.new` for how this is defined. The context from
+  # the `default_scientist_context` method will be applied to the experiment.
+  #
+  # Returns the calculated value of the control experiment, or raises if an
+  # exception was raised.
+  def science(name, opts = {})
+    Scientist.run(name, opts) do |experiment|
+      experiment.context(default_scientist_context)
+
+      yield experiment
+    end
+  end
+
   # Public: the default context data for an experiment created and run via the
   # `science` helper method. Override this in any class that includes Scientist
   # to define your own behavior.

data/lib/scientist/default.rb

@@ -10,9 +10,9 @@ class Scientist::Default
     @name = name
   end
 
-  # Run everything every time.
+  # Don't run experiments.
   def enabled?
-    true
+    false
   end
 
   # Don't publish anything.

data/lib/scientist/version.rb

@@ -1,3 +1,3 @@
 module Scientist
-  VERSION = "1.1.0"
+  VERSION = "1.1.1"
 end

data/script/release

@@ -14,7 +14,7 @@ gem build -q scientist.gemspec
 
 # Make sure we're on the master branch.
 
-(git branch | grep -q '* master') || {
+(git branch --no-color | grep -q '* master') || {
   echo "Only release from the master branch."
   exit 1
 }

data/test/scientist/default_test.rb

@@ -3,8 +3,8 @@ describe Scientist::Default do
     @ex = Scientist::Default.new "default"
   end
 
-  it "is always enabled" do
-    assert @ex.enabled?
+  it "is always disabled" do
+    refute @ex.enabled?
   end
 
   it "noops publish" do

data/test/scientist/experiment_test.rb

@@ -123,6 +123,11 @@ describe Scientist::Experiment do
   it "re-raises exceptions raised during publish by default" do
     ex = Scientist::Experiment.new("hello")
     assert_kind_of Scientist::Default, ex
+
+    def ex.enabled?
+      true
+    end
+
     def ex.publish(result)
       raise "boomtown"
     end

data/test/scientist_test.rb

@@ -15,6 +15,15 @@ describe Scientist do
     assert_equal :control, r
   end
 
+  it "provides a module method to instantiate and run experiments" do
+    r = Scientist.run "test" do |e|
+      e.use { :control }
+      e.try { :candidate }
+    end
+
+    assert_equal :control, r
+  end
+
   it "provides an empty default_scientist_context" do
     obj = Object.new
     obj.extend(Scientist)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: scientist
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.1.1
 platform: ruby
 authors:
 - GitHub Open Source
@@ -12,34 +12,34 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-08-29 00:00:00.000000000 Z
+date: 2018-02-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '5.8'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '5.8'
 - !ruby/object:Gem::Dependency
   name: coveralls
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '0.8'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '0.8'
 description: A Ruby library for carefully refactoring critical paths
@@ -53,8 +53,8 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- .gitignore
-- .travis.yml
+- ".gitignore"
+- ".travis.yml"
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -85,17 +85,17 @@ 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.14.1
+rubygems_version: 2.7.3
 signing_key: 
 specification_version: 4
 summary: Carefully test, measure, and track refactored code.