Overhaul documentation.

CONTRIBUTING.rst

@@ -0,0 +1,73 @@
+.. _about-contributing:
+.. highlight:: shell
+
+======================
+Contributing to Waffle
+======================
+
+Waffle is pretty simple to hack, and has a decent test suite! Here's how
+to patch Waffle, add tests, run them, and contribute changes.
+
+**Please** `open a new issue`_ to discuss a new feature before beginning
+work on it. Not all suggestions are accepted. The Goals_ may help guide
+which features are likely to be accepted.
+
+
+Set Up
+======
+
+Setting up an environment is easy! You'll want ``virtualenv`` and
+``pip``, then just create a new virtual environment and install the
+requirements::
+
+    $ mkvirtualenv waffle
+    $ pip install -r requirements.txt
+
+Done!
+
+
+Writing Patches
+===============
+
+Fork_ Waffle and create a new branch off master for your patch. Run the
+tests often::
+
+    $ ./run.sh test
+
+Try to keep each branch to a single feature or bugfix.
+
+.. note::
+
+    To update branches, please **rebase** onto master, do not merge
+    master into your branch.
+
+
+Submitting Patches
+==================
+
+Open a pull request on GitHub!
+
+Before a pull request gets merged, it should be **rebased** onto master
+and squashed into a minimal set of commits. Each commit should include
+the necessary code, test, and documentation changes for a single "piece"
+of functionality.
+
+To be mergable, patches must:
+
+- be rebased onto the latest master,
+- be automatically mergeable,
+- not break existing tests (TravisCI_ will run them, too),
+- not change existing tests without a *very* good reason,
+- add tests for new code (bug fixes should include regression tests, new
+  features should have relevant tests),
+- not introduce any new flake8_ errors (run ``./run.sh lint``) and
+- document any new features.
+
+Regressions tests should fail without the rest of the patch and pass
+with it. 
+
+
+.. _open a new issue: https://github.com/jsocol/django-waffle/issues/new
+.. _Fork: https://github.com/jsocol/django-waffle/fork
+.. _TravisCI: https://travis-ci.org/jsocol/django-waffle
+.. _flake8: https://pypi.python.org/pypi/flake8

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2011, 2012 James Socol
+Copyright (c) 2015 James Socol
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without modification,

docs/about/contributing.rst

@@ -0,0 +1,73 @@
+.. _about-contributing:
+.. highlight:: shell
+
+======================
+Contributing to Waffle
+======================
+
+Waffle is pretty simple to hack, and has a decent test suite! Here's how
+to patch Waffle, add tests, run them, and contribute changes.
+
+**Please** `open a new issue`_ to discuss a new feature before beginning
+work on it. Not all suggestions are accepted. The :ref:`Goals
+<about-goals>` may help guide which features are likely to be accepted.
+
+
+Set Up
+======
+
+Setting up an environment is easy! You'll want ``virtualenv`` and
+``pip``, then just create a new virtual environment and install the
+requirements::
+
+    $ mkvirtualenv waffle
+    $ pip install -r requirements.txt
+
+Done!
+
+
+Writing Patches
+===============
+
+Fork_ Waffle and create a new branch off master for your patch. Run the
+tests often::
+
+    $ ./run.sh test
+
+Try to keep each branch to a single feature or bugfix.
+
+.. note::
+
+    To update branches, please **rebase** onto master, do not merge
+    master into your branch.
+
+
+Submitting Patches
+==================
+
+Open a pull request on GitHub!
+
+Before a pull request gets merged, it should be **rebased** onto master
+and squashed into a minimal set of commits. Each commit should include
+the necessary code, test, and documentation changes for a single "piece"
+of functionality.
+
+To be mergable, patches must:
+
+- be rebased onto the latest master,
+- be automatically mergeable,
+- not break existing tests (TravisCI_ will run them, too),
+- not change existing tests without a *very* good reason,
+- add tests for new code (bug fixes should include regression tests, new
+  features should have relevant tests),
+- not introduce any new flake8_ errors (run ``./run.sh lint``) and
+- document any new features.
+
+Regressions tests should fail without the rest of the patch and pass
+with it. 
+
+
+.. _open a new issue: https://github.com/jsocol/django-waffle/issues/new
+.. _Fork: https://github.com/jsocol/django-waffle/fork
+.. _TravisCI: https://travis-ci.org/jsocol/django-waffle
+.. _flake8: https://pypi.python.org/pypi/flake8

docs/about/goals.rst

@@ -0,0 +1,23 @@
+.. _about-goals:
+
+==============
+Waffle's goals
+==============
+
+.. note::
+
+    This document is a work in progress. See :ref:`the roadmap
+    <about-roadmap>`, too.
+
+Waffle is designed to
+
+- support continuous integration and deployment,
+- support feature rollout,
+- with minimum set-up time and learning,
+- while covering common segments,
+- and being fast and robust enough for production use.
+
+Waffle is **not** designed to
+
+- be secure, or be a replacement for permissions,
+- cover all potential segments.

docs/about/roadmap.rst

@@ -0,0 +1,108 @@
+.. _about-roadmap:
+
+=======
+Roadmap
+=======
+
+.. note::
+
+    This roadmap is subject to change, but represents the rough
+    direction I plan to go. For specific issues, see the current
+    milestones_.
+
+
+Waffle is already a useful library used in many production systems, but
+it is not done evolving.
+
+
+Present through 0.12
+=====================
+
+The immediate future is finishing common segment features and bug fixes.
+
+
+0.10.2/0.11
+-----------
+
+0.10.2_ was primarily a docs overhaul with a major fix to how caching
+works. It will probably not be released on its own but combined with
+0.11_.
+
+0.11 includes a couple of significant refactors designed to pay down
+some of the debt that's accrued in the past few years. It also includes
+finally making a decision about auto-create/data-in-settings. There are
+also a few small tools like template syntax sugar and and integration
+testing tools.
+
+
+0.12
+----
+
+0.12_ is about closing some long-standing feature gaps, like segmenting
+by IP and User-Agent.
+
+
+Toward 1.0
+==========
+
+There are no solid criteria for what makes 1.0 right now, but after
+0.12, most outstanding issues will be resolved and Waffle will be in
+very good shape. There are no plans for a 0.13, so it seems likely that
+the next step after 0.12 would be some clean-up and finally a 1.0.
+
+
+Beyond 1.0
+==========
+
+*tl;dr: Waffle2 may be a complete break from Waffle.*
+
+Waffle is one of the first Python libraries I created, you can see that
+in the amount of code I left in ``__init__.py``. It is also 4 years old,
+and was created during a different period in my career, and in Django.
+
+There are some philosophical issues with how Waffle is designed. Adding
+new methods of segmenting users requires at least one new column each,
+and increasing the cyclomatic complexity. Caching is difficult. The
+requirements are stringent and no longer realistic (they were created
+before Django 1.5). The distinction between Flags, Samples, and Switches
+is confusing and triples the API surface area (Flags can easily act as
+Switches, less easily as Samples). It is not extensible.
+
+Some challenges also just accrue over time. Dropping support for Django
+1.4, the current Extended Support Release, would significantly simplify
+a few parts.
+
+There is a simplicity to Waffle that I've always appreciated vs, say,
+Gargoyle_. Not least of which is that Waffle works with the built-in
+admin (or any other admin you care to use). I don't have to write any
+code to start using Waffle, other than an ``if`` block. Just add a row
+and click some checkboxes. Most batteries are included. These are all
+things that any new version of Waffle must maintain.
+
+Still, if I *want* to write code to do some kind of custom segment that
+isn't common-enough to belong in Waffle, shouldn't I be able to? (And,
+if all the core segmenters were built as the same kind of extension, we
+could lower the bar for inclusion.) If I only care about IP address and
+percentage, it would be great to skip all the other checks that just
+happen to be higher in the code.
+
+I have rough sketches of what this looks like, but there are still some
+significant sticking points, particularly around shoehorning all of this
+into the existing Django admin. I believe it's *possible*, just
+potentially *gross*. (Then again, if it's gross underneath but exposes a
+pleasant UI, that's not ideal, but it's OK.)
+
+The other big sticking point is that this won't be a simple ``ALTER
+TABLE wafle_flag ADD COLUMN`` upgrade; things will break. 
+
+I've been thinking what Waffle would be like if I designed it from
+scratch today with slightly different goals, like extensibility. Beyond
+1.0, it's difficult to see continuing to add new features without this
+kind of overhaul.
+
+
+.. _milestones: https://github.com/jsocol/django-waffle/milestones
+.. _0.10.2: https://github.com/jsocol/django-waffle/milestones/0.10.2
+.. _0.11: https://github.com/jsocol/django-waffle/milestones/0.11
+.. _0.12: https://github.com/jsocol/django-waffle/milestones/0.12
+.. _Gargoyle: https://github.com/disqus/gargoyle

docs/about/why-waffle.rst

@@ -0,0 +1,49 @@
+.. _about-why-waffle:
+
+===========
+Why Waffle?
+===========
+
+`Feature flags`_ are a critical tool for continuously integrating and
+deploying applications. Waffle is one of `several options`_ for managing
+feature flags in Django applications.
+
+Waffle :ref:`aims to <about-goals>`
+
+- provide a simple, intuitive API everywhere in your application;
+- cover common use cases with batteries-included;
+- be simple to install and manage;
+- be fast and robust enough to use in production; and
+- minimize dependencies and complexity.
+
+Waffle has an `active community`_ and gets `fairly steady updates`_.
+
+
+vs Gargoyle
+===========
+
+The other major, active feature flag tool for Django is Disqus's
+Gargoyle_. Both support similar features, though Gargoyle offers more
+options for building custom segments in exchange for some more
+complexity and requirements.
+
+
+Waffle in Production
+====================
+
+Despite its pre-1.0 version number, Waffle has been used in production
+for years at places like Mozilla, Yipit and TodaysMeet.
+
+- Mozilla (Support, MDN, Addons, etc)
+- TodaysMeet
+- Yipit
+
+(If you're using Waffle in production and don't mind being included
+here, let me know or add yourself in a pull request!)
+
+
+.. _Feature flags: http://code.flickr.net/2009/12/02/flipping-out/
+.. _several options: https://www.djangopackages.com/grids/g/feature-flip/
+.. _active community: https://github.com/jsocol/django-waffle/graphs/contributors
+.. _fairly steady updates: https://github.com/jsocol/django-waffle/pulse/monthly
+.. _Gargoyle: https://github.com/disqus/gargoyle

docs/conf.py

@@ -25,7 +25,7 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = []
+extensions = ['sphinx.ext.mathjax']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']