Update docs

Author: keathley

README.md

@@ -1,21 +1,88 @@
 # Rollout
 
-**TODO: Add description**
+Rollout allows you to flip features quickly and easily. It relies on
+distributed erlang and uses LWW-Register and Hybrid-logical clocks
+to provide maximum availability. Rollout has no dependency on an external
+service such as redis which means rollout feature flags can be used in the
+critical path of a request with minimal latency increase.
 
-## Installation
+* [Docs](https://hexdocs.pm/rollout).
 
-If [available in Hex](https://hex.pm/docs/publish), the package can be installed
-by adding `rollout` to your list of dependencies in `mix.exs`:
+## Installation
 
 ```elixir
 def deps do
   [
-    {:rollout, "~> 0.1.0"}
+    {:rollout, "~> 0.1"}
   ]
 end
 ```
 
-Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc)
-and published on [HexDocs](https://hexdocs.pm). Once published, the docs can
-be found at [https://hexdocs.pm/rollout](https://hexdocs.pm/rollout).
+## Usage
+
+Rollout provides a simple api for enabling and disabling feature flags across
+your cluster. A feature flag can be any term.
+
+```elixir
+# Check if a feature is active
+Rollout.active?(:blog_post_comments)
+# => false
+
+# Activate the feature
+Rollout.activate(:blog_post_comments)
+
+# De-activate the feature
+Rollout.deactivate(:blog_post_comments)
+```
+
+You can also activate a feature a certain percentage of the time.
+
+```elixir
+Rollout.activate_percentage(:blog_post_comments, 20)
+```
+
+You can run this function on one node in your cluster and the updates will
+be propogated across the system. This means that updates to feature flags may
+not be instantaneous across the cluster but under normal conditions should propogate
+quickly. This is a tradeoff I've made in order to maintain the low latency when
+checking if a flag is enabled.
+
+## How does Rollout work?
+
+Rollout maintains a LWW Register for each flag that has been activated or
+deactivated. These Registers use hybrid logical clocks (HLC) for causality
+tracking. When a flag is activated or deactivated we update the HLC for that
+register and propogate that change across the cluster. When merging registers
+across the cluster we always take register with the latest HLC. After merging is
+done we store the values for each register into an ets table for fast lookups.
+
+## Caveats
+
+Rollout relies on your nodes being connected through distributed erlang. If you
+are running your application on more than one node and you are not clustering than
+your changes won't propogate. You will need to run the command on all nodes but
+in practice you'll probably just want to look for an alternative solution.
+
+Flags are *not* maintained in between node restarts. New nodes added to your cluster
+will be caught up on the current state. But if you bring up an entirely new cluster
+your flags will revert to their default states. You can mitigate this problem
+by setting defaults for each flag in your `Application.start/2` callback.
+
+Because we're using CRDTs to propogate changes its possible that a change made
+on one node will take time to propogate to the other nodes. Its a safe operation
+to run the same operation on multiple nodes. When feature flags are merged we
+also default to the latest HLC.
+
+## Should I use this?
+
+For now I'd say "No". The functionality works but this repo currently has 0
+tests and I'm sure there are edge cases. You should also not cluster your
+application for the sole purpose of using this library. If you need this
+you'll know it. Otherwise you're better off looking at an alternative solution.
+
+## Future work
+
+I'd like to implement an alternative storage engine for use in non-clustered
+environments, preferably using a fast storage engine such as redis. If anyone
+wants to submit that PR I'd love to take a look at it.
 

lib/rollout.ex

@@ -1,6 +1,48 @@
 defmodule Rollout do
   @moduledoc """
-  Documentation for Rollout.
+  Rollout allows you to flip features quickly and easily. It relies on
+  distributed erlang and uses LWW-register and Hybrid-logical clocks
+  to provide maximum availability. Rollout has no dependency on an external
+  service such as redis which means rollout feature flags can be used in the
+  critical path of a request with minimal latency increase.
+
+  ## Usage
+
+  Rollout provides a simple api for enabling and disabling feature flags across
+  your cluster. A feature flag can be any term.
+
+  ```elixir
+  # Check if a feature is active
+  Rollout.active?(:blog_post_comments)
+  # => false
+
+  # Activate the feature
+  Rollout.activate(:blog_post_comments)
+
+  # De-activate the feature
+  Rollout.deactivate(:blog_post_comments)
+  ```
+
+  You can also activate a feature a certain percentage of the time.
+
+  ```elixir
+  Rollout.activate_percentage(:blog_post_comments, 20)
+  ```
+
+  You can run this function on one node in your cluster and the updates will
+  be propogated across the system. This means that updates to feature flags may
+  not be instantaneous across the cluster but under normal conditions should propogate
+  quickly. This is a tradeoff I've made in order to maintain the low latency when
+  checking if a flag is enabled.
+
+  ## How does Rollout work?
+
+  Rollout maintains a LWW Register for each flag that has been activated or
+  deactivated. These Registers use hybrid logical clocks (HLC) for causality
+  tracking. When a flag is activated or deactivated we update the HLC for that
+  register and propogate the register across the cluster. When merging registers
+  we always take register with the latest HLC. After merging is
+  done we store the values for each register into an ets table for fast lookups.
   """
 
   alias Rollout.Storage

lib/rollout/storage.ex

@@ -1,5 +1,11 @@
 defmodule Rollout.Storage do
   @moduledoc false
+  # This module provides a server for maintaining flags. It monitors node
+  # connects in order to propogate existing flag information. Currently it
+  # manages the ets table we're using for holding the value for each flag.
+  # This isn't a great design because if we crash we lose the ets table.
+  # We should make that ets table public and move its creation to a supervisor
+  # or application start.
 
   use GenServer
 

mix.exs

@@ -31,14 +31,15 @@ defmodule Rollout.MixProject do
   defp deps do
     [
       {:hlclock, "~> 1.0"},
+      {:ex_doc, ">= 0.0.0", only: :dev}
     ]
   end
 
   def description do
     """
     Rollout allows you to flip features quickly and easily. It relies on
-    distributed erlang and uses LWW-register CRDTs and Hybrid-logical clocks
-    to provide maximum availability.
+    distributed erlang and uses LWW-Registers and Hybrid-logical clocks
+    to provide maximum availability and low latency.
     """
   end
 

mix.lock

@@ -1,3 +1,8 @@
 %{
+  "earmark": {:hex, :earmark, "1.3.5", "0db71c8290b5bc81cb0101a2a507a76dca659513984d683119ee722828b424f6", [:mix], [], "hexpm"},
+  "ex_doc": {:hex, :ex_doc, "0.21.1", "5ac36660846967cd869255f4426467a11672fec3d8db602c429425ce5b613b90", [:mix], [{:earmark, "~> 1.3", [hex: :earmark, repo: "hexpm", optional: false]}, {:makeup_elixir, "~> 0.14", [hex: :makeup_elixir, repo: "hexpm", optional: false]}], "hexpm"},
   "hlclock": {:hex, :hlclock, "1.0.0", "7a72fc7a20a9382499216227edf97a8b118e21fc3fcad0e81b8d10c616ce1431", [:mix], [], "hexpm"},
+  "makeup": {:hex, :makeup, "1.0.0", "671df94cf5a594b739ce03b0d0316aa64312cee2574b6a44becb83cd90fb05dc", [:mix], [{:nimble_parsec, "~> 0.5.0", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm"},
+  "makeup_elixir": {:hex, :makeup_elixir, "0.14.0", "cf8b7c66ad1cff4c14679698d532f0b5d45a3968ffbcbfd590339cb57742f1ae", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm"},
+  "nimble_parsec": {:hex, :nimble_parsec, "0.5.1", "c90796ecee0289dbb5ad16d3ad06f957b0cd1199769641c961cfe0b97db190e0", [:mix], [], "hexpm"},
 }