Merge pull request #2051 from alphagov/documentation-for-feature-flags

Add documentation about feature flags

README.md

@@ -61,6 +61,10 @@ This will generate a diagram in the `docs/state_machines` folder.
 
 Publisher stores its data in DocumentDB, which can't be queried using the instructions detailed in the GOV.UK developer docs. Instead, follow [these instructions for querying the database](docs/database-querying.md). 
 
+### Feature flags
+
+For details on how feature flags are managed in Publisher, see the [feature flags documentation](docs/feature-flags.md).
+
 ## Further documentation
 
 - [Fact Checking](docs/fact-checking.md)

docs/feature-flags.md

@@ -0,0 +1,47 @@
+# Feature flags
+
+Feature flags in Publisher are managed using the [Flipflop gem](https://github.com/voormedia/flipflop). The gem is currently
+configured so that only the "cookie" and "default" strategies are active.
+
+## Toggling feature flags
+
+A features dashboard is available to make it easy to toggle features on and off during development.
+This dashboard can be accessed at `/flipflop`. Note that this can only be used to toggle feature flags for your user.
+
+## Testing with feature flags
+
+For testing purposes, feature flags can be configured like so:
+
+```ruby
+  setup do
+    test_strategy = Flipflop::FeatureSet.current.test!
+    test_strategy.switch!(:feature_name, true)
+  end
+```
+
+## Creating a feature flag
+
+To create a new feature flag, create an entry in the [features.rb](../config/features.rb) file with this format:
+
+```ruby
+feature :feature_name,
+      default: false,
+      description: "A description of the feature"
+```
+
+Features should default to `false` while being worked on, meaning users will not see any change without explicitly turning the feature on using the dashboard.
+
+To route the user between different pages based on the status of a feature flag, use the [FeatureConstraint class](../app/constraints/feature_constraint.rb).
+
+For example:
+
+```ruby
+app/routes.rb
+
+constraints FeatureConstraint.new("feature_name") do
+  get "path/to/page" => "new_controller#action"
+end
+get "path/to/page" => "old_controller#action"
+```
+
+This will route GET requests for `/path/to/page` to `new_controller` when the feature flag is enabled, and to `old_controller` when it is disabled.