moses-vanity 1.7.1

data/doc/configuring.textile

@@ -0,0 +1,45 @@
+---
+layout: page
+title: Configuring the Playground
+---
+
+Vanity will work out of the box on a default configuration.  Assuming you're using Redis on localhost, post 6379, there's nothing special to do.
+
+Database connection information is loaded from @config/vanity.yml@, based on the current environment (@RACK_ENV@ or @RAILS_ENV@). Example:
+
+<pre>
+development:
+  adapter: redis
+  connection: redis://localhost:6379/0
+production:
+  adapter: mongodb
+  database: analytics
+</pre>
+
+If there's no configuration file and the application does not create a connection explicitly, Vanity will default to the Redis instance running on @localhost@ at port 6379.
+
+The available database adapters are:
+
+* +redis+ -- This adapter is used by default. Available options are connection and password. host, port, database (defaults to 0) options are available, but deprecated.
+* +mongodb+ -- Available options are host, port, database (defaults to "vanity"), username and password.
+* +active_record+ -- Uses existing ActiveRecord configuration, by you can over-ride by supplying different options. To pick different underlying adapter, set +active_record_adapter+.
+
+You want Vanity to collect information (metrics, experiments, etc) in production, but there's no point collecting data in other environments. You can turn data collection on and off by setting @Vanity.playground.collecting@. Under Rails, collection is turned off in all environments expect production.
+
+You may want to turn data collection on for integration tests, depending on what you're testing. Also, you may need to turn it on if your development server runs more than one process, e.g. if you're using Passenger for development and want to use the Vanity console to pick a particular alternative in an A/B test.
+
+Available configuration options are:
+
+|_. name      |_. Is all about ...                      |_. Default      |
+| load_path   | Directory containing experiment files   | experiments    |
+| logger      | This should be obvious                  | default/Rails  |
+| collecting  | False if you won't want data collected  | true           |
+
+When "running under Rails":rails.html, Vanity defaults to using the Rails logger, locates the load_path relative to Rails root, uses the @config/vanity.yml@ configuration file (if present) and turns collection on only in production mode.
+
+If you run a different setup, use the playground object to configure Vanity.  For example:
+
+<pre>
+Vanity.playground.load_path = "exp"
+Vanity.playground.establish_connection "redis://db.example.com"
+</pre>

data/doc/contributing.textile

@@ -0,0 +1,93 @@
+---
+layout: page
+title: Contributing
+---
+
+<div id="toc">
+# "How To Contribute":#contributing
+# "Building From Source":#building
+# "Documentation":#doc
+# "Open Issues":#open
+</div>
+
+By all means.
+
+
+h3(#contributing).  How To Contribute
+
+Pick on an "open issue":http://github.com/assaf/vanity/issues, "experimental feature":experimental.html, suggestion from the "Google Group":http://groups.google.com/group/vanity-talk, or whatever you feel like contributing.
+
+To contribute new code/changes:
+# "Fork the project":http://github.com/assaf/vanity
+# Please use a topic branch to make your changes, it's easier to test them that way
+# Fix, patch, enhance, document, improve, sprinkle pixie dust
+# Tests. Please. Run @rake@ and if possible CI (see below)
+# Send a pull request on GitHub
+
+Bonus points for helping improve the documentation, writing some examples, and adding more test coverage.
+
+
+h3(#building). Building From Source
+
+Vanity is tested against multiple Ruby implementations, and a variety of database engines. To make life easier, we use "RVM":http://rvm.beginrescueend.com/ and "Bundler":http://gembundler.com/ to set up the test/development environment.
+
+To test Vanity for the first time under whichever Ruby implementation you're currently using:
+
+<pre>
+$ rake test:setup
+$ rake
+</pre>
+
+To test Vanity with specific database adapter:
+
+<pre>
+$ rake DB=redis
+$ rake DB=mongodb
+$ rake DB=mysql
+</pre>
+
+
+Before making a release, we run the full test suite against multiple Ruby VMs
+and using multiple database adapters.  Doing this on your own is easier than it
+sounds:
+
+# "Fork the project":http://github.com/assaf/vanity
+# Go to "Travis CI":http://travis-ci.org/, setup a new account if you don't already have one
+# "In your profile page":http://travis-ci.org/profile, tell Travis to build your fork
+# @git push@ your changes into your fork and "watch Travis":http://travis-ci.org/ run the tests
+
+
+To package Vanity as a gem and install on your machine:
+
+<pre>
+$ rake install
+</pre>
+
+
+h3(#doc). Documentation
+
+Documentation is written in "Textile":http://redcloth.org/textile/writing-paragraph-text/, and converted to HTML using "Jekyll":http://jekyllrb.com/.
+
+API reference is "RDoc":http://rdoc.sourceforge.net/doc/index.html, converted to HTML using "Yardoc":http://yardoc.org/. 
+
+To build and view documentation:
+
+<pre>
+$ rake docs
+$ open html/index.html
+</pre>
+
+To clean up after yourself:
+
+<pre>
+$ rake clobber
+</pre>
+
+
+h3(#open). Open Issues
+
+<notextile>
+<table id="issues">
+  <tbody></tbody>
+</table>
+</notextile>

data/doc/credits.textile

@@ -0,0 +1,23 @@
+---
+layout: page
+title: Credits
+---
+
+Made better by:
+Adam Keys
+Brian Leonard
+JS Boulanger
+Ryan Carver
+Stephen Celis
+
+Experiment Driven Development conceived by "Nathaniel Talbott":http://blog.talbott.ws.
+
+A/B tests, influenced by Patrick McKenzie's awesome "A/Bingo":http://www.bingocardcreator.com/abingo.
+
+"jQuery":http://jquery.com, copyright of John Resig, released under the "MIT license":http://dev.jquery.com/browser/trunk/jquery/MIT-LICENSE.txt.
+
+"Flot":http://code.google.com/p/flot/, copyright of IOLA and Ole Laursen, released under the "MIT license":http://code.google.com/p/flot/source/browse/trunk/LICENSE.txt.
+
+Original code, copyright of "Assaf Arkin":http://labnotes.org, released under the "MIT license":http://github.com/assaf/vanity/blob/master/MIT-LICENSE.
+
+Documentation available under the "Creative Commons Attribution":http://creativecommons.org/licenses/by/3.0/ license.

data/doc/css/page.css

@@ -0,0 +1,83 @@
+body {
+  font: 13pt "Geneva", "Lucida Sans", "Lucida Grande", "Lucida Sans Unicode", Verdana, sans-serif;
+  line-height: 1.5em;
+  margin: 2em auto;
+  background-color: #fff;
+  color: #444;
+}
+a:link { color: #4488f7; text-decoration: none }
+a:visited { color: #4488f7; text-decoration: none }
+a:hover { text-decoration: underline }
+img { border: 1px solid #eee; padding: 16px; margin: 0 auto; display: block }
+blockquote { padding-left: 2em; padding-right: 2em; margin-left: 0.3em; margin-right: 0; font-style: italic }
+ul { list-style-type: disc; padding-left: 1.2em }
+ul ul { list-style-type: disc; padding-left: 1em }
+table { border-spacing: 0; width: 100%; margin: 0.3em 0 0.3em 0 }
+th, td { padding: 0.3em 0.5em 0.3em 0.5em; border-bottom: 1px solid #D8D8D8; vertical-align: top; background-color: #FFF }
+th, thead td { border-bottom: none; background-color: #669966; color: #fff; text-align: left }
+
+pre, code {
+  font-family: "Andale Mono", "DejaVu Sans Mono", "Courier New", "Courier", monospace;
+  font-size: 11pt;
+  color: #222;
+}
+pre {
+  line-height: 1.2em;
+  padding: 0.6em 0 0.6em 1em;
+  white-space: pre-wrap;
+  background: #eef;
+  white-space: -moz-pre-wrap !important;
+}
+pre br {
+  display: none;
+}
+
+h1, h2, h3, h3, #header, #links, #sidebar {
+  font-family: "Gill Sans", "Trebuchet MS", "Calibri", sans-serif;
+  margin: 0;
+  color: #222;
+}
+h2 { font-size: 1.5em }
+h3 { font-size: 1.2em; margin-top: 2.5em }
+h4 { font-size: 1.0em; margin-top: 1.5em }
+/*line-height: 1.25em; letter-spacing: 0.03em; color: #87C72E; */
+
+.title { margin: 12pt 0 0 0; font-size: 48pt; font-weight: bold; letter-spacing: -2px; line-height: 48pt }
+.title a { color: #000 !important }
+.tagline { margin: -34pt 0 1.5em 9em; font-size: 18pt; font-weight: normal; color: #aaa; line-height: 18pt }
+
+.footnote { font-size: 90%; margin-top: 4em }
+.footnote+.footnote { margin-top: .6em }
+#links { position: fixed; right: 0; top: 0; padding: .6em; color: #ccc }
+#header, #content, #footer { width: 40em; margin-left: 210px }
+#sidebar { float: left; width: 140px; margin: 20px }
+#sidebar ul { list-style: none; text-align: right; margin: 0 0 3em 0; padding: 0 }
+#sidebar ul a img { border: none; margin; 0; padding: 0 }
+#sidebar ul#stats { color: #666 }
+table#issues .votes { color: #ccc; float: right }
+#content { padding: 1.35em 0 }
+#footer { clear: both; padding: 0; margin-top: 3em; border-top: 1px solid #ccc; text-align: right }
+
+#toc ol {
+  margin: 1em 0 2em 0.6em;
+  list-style-type: disc;
+  padding-left: 1em;
+  font-size: 0.9em;
+}
+#toc li {
+  margin: .3em 0;
+}
+
+.experimental {
+  font-family: "Rough Draft", "Stencil", "Tahoma", "sans-serif";
+  content: "Experimental";
+  text-transform: uppercase;
+  color: rgba(255,0,0,0.65);
+  font-size: 36pt;
+  position: absolute;
+  margin-top: -4em;
+  margin-left: 2em;
+  -webkit-transform: rotate(-15deg); 
+  -moz-transform: rotate(-15deg); 
+}
+

data/doc/css/print.css

@@ -0,0 +1,43 @@
+body {
+  color: #000;
+  background: #fff;
+  width: 220mm;
+  margin: 0;
+  text-rendering: optimizeLegibility;
+  font-size: 14pt;
+}
+.title, .tagline {
+  display: none;
+}
+h1 {
+  page-break-before: always;
+}
+h1:first-child {
+  page-break-before: avoid;
+}
+h1, h2, h3 {
+  color: black;
+}
+pre, p, blockquote, table {
+  page-break-inside: avoid;
+}
+pre, code {
+  margin: 0;
+  font-size: 13pt;
+}
+a:link, a:visited {
+  background: transparent;
+  text-decoration: none;
+  color: #0044b3;
+}
+
+#links, #sidebar, #footer {
+  display: none;
+}
+#content {
+  color: black;
+  padding: 0;
+  border: 0;
+  margin-left: 0;
+  width: 100% !important;
+}

data/doc/css/syntax.css

@@ -0,0 +1,7 @@
+.highlight .k, .highlight .kp { color: blue } /* keyword */
+.highlight .no { color: darkblue } /* constant */
+.highlight .s1 { color: green } /* string */
+.highlight .n { color: black } /* identifier */
+.highlight .o, .highlight .p { color: darkblue } /* = + */
+.highlight .ss { color: darkblue } /* symbol */
+.highlight .c1 { color: gray } /* comment */

data/doc/email.textile

@@ -0,0 +1,129 @@
+---
+layout: page
+title: Testing Emails
+---
+
+<div id="toc">
+# "Configuring ActionMailer":#config
+# "Testing email subject lines":#subject
+# "Testing email content":#content
+</div>
+
+h3(#config).  Configuring ActionMailer
+
+First setup Rails to send email. For example, if you are using GMail you can setup your SMTP settings like this:
+
+<pre>
+ActionMailer::Base.smtp_settings = {
+  :address => "smtp.gmail.com",
+  :port => "587",
+  :domain => "gmail.com",
+  :authentication => :plain,
+  :user_name => "your-email@gmail.com",
+  :password => "your-pass"
+}
+</pre>
+
+
+h3(#subject).  Testing email subject lines
+
+In your @RAILS_ROOT/experiments/@ folder create an experiment file. For example:
+
+<pre>
+ab_test "Invite subject" do
+  description "Optimize invite subject line"
+  alternatives "Join now!", "You're invited to an exclusive event."
+  metrics :open
+end
+</pre>
+
+In your @RAILS_ROOT/experiments/metrics/@ folder create a metric file for the metric you are testing. For example:
+
+<pre>
+metric "Open (Activation)" do
+  description "Measures how many recipients opened an email."
+end
+</pre>
+
+Create an ActionMailer class, for example:
+
+<pre>
+class UserMailer < ActionMailer::Base 
+  def invite_email(user)
+    use_vanity_mailer user
+    mail :to => user.email, :subject =>ab_test(:invite_subject)
+  end
+end
+</pre>
+
+We set the identity of the "user" in the @use_vanity_mailer@ method. This can take a string or an object that responds to id. If it's nil then it will set it as a random number. Setting the appropriate context is important to have each user consistently get the same alternative in our experiment.
+
+Now we need to include a tracking image in the email content.  We pass in the vanity identity which we set when we called @use_vanity_mailer(user)@ and the metric we are tracking.
+
+<pre>
+  <!DOCTYPE html>
+  <html>
+    <head>
+      <meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
+    </head>
+    <body>
+      <h1>Hey Joseph</h1>
+      <p>
+        <%= vanity_tracking_image(Vanity.context.vanity_identity, :open, :host => "127.0.0.1:3000") %>
+      </p>
+    </body>
+  </html>
+</pre>
+
+Last, we have to include the @TrackingImage@ module into our @VanityController@.  This is the same place that you can include the @Dashboard@.
+
+@Vanity::Rails::TrackingImage@ will add a image method that will render a blank image.
+
+<pre>
+class VanityController < ApplicationController
+  include Vanity::Rails::Dashboard
+  include Vanity::Rails::TrackingImage
+end
+</pre>
+
+
+h3(#subject).  Testing email content
+
+In your @RAILS_ROOT/experiments/@ folder create a new experiment file:
+
+<pre>
+ab_test "Invite text" do
+  description "Optimize invite text"
+  alternatives "A friend of yours invited you to use Vanity", "Vanity is the latest and greatest in a/b testing technology"
+  metrics :click
+end
+</pre>
+
+In your @RAILS_ROOT/experiments/metrics/@ folder create a metric file for the metric you are testing:
+
+<pre>
+metric "Click (Acquisition)" do
+  description "Measures clickthough on email."
+end
+</pre>
+
+A/B test your email content:
+
+<pre>
+  <!DOCTYPE html>
+  <html>
+    <head>
+      <meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
+    </head>
+    <body>
+      <h1>Hi!</h1>
+      <p>
+        <%= link_to ab_test(:invite_text), vanity_track_url_for(Vanity.context.vanity_identity, :click, :controller => "home", :action => "index", :host => "127.0.0.1:3000") %>
+      </p>
+    </body>
+  </html>
+</pre>
+
+Here we use the text from the "invite_text" experiment and then use the @vanity_track_url_for@ helper to add the identity and the metric to track into the url so that Vanity can track the click-throughs.
+
+Remember: By default, Vanity only collects data in production mode.

data/doc/experimental.textile

@@ -0,0 +1,31 @@
+---
+layout: page
+title: Experimental Features
+---
+
+<div id="toc">
+# "Multi-series Metrics":#multi-series
+</div>
+
+<div class="experimental">Experimental</div>
+
+Everything on this page is work-in-progress towards some future release. Interested in picking up any of these features and developing them further?
+
+
+h3(#multi-series).  Multi-series Metrics
+
+Vanity 1.4 introduces some changes to the API to allow support for multi-series metrics. The intent is to allow more data to be captured and displayed using less metrics (i.e. charts).
+
+First change to the @track!@ method, which now accepts a single value, array of values, or hash. Since incrementing the metric by one is quite common, this is still the default behavior when calling @track!@ with no arguments.
+
+Next proposed change would allow the metric to define multiple columns. Those can be addressed by name or index, for example:
+
+<pre>
+metric :purchase do
+  columns :count, :total
+end
+metric(:purchase).track! p.items.length. p.total
+metric(:purchase).track! :total=>p.total, :count=>p.items.length
+</pre>
+
+The metric's @values@ method will have to be changed to return an array of arrays, or new method introduced to keep the API backward compatible. And, of course, UI modified to display multiple series in a single graph.