How Feature Flags Work

We're not going to go into details about what feature flags (or feature toggles, flips or other such names as they are commonly called) are here, rather how they work in Bandiera. For more information on feature flagging and how useful the practice can be, see these notes:

• http://en.wikipedia.org/wiki/Feature_toggle
• http://code.flickr.net/2009/12/02/flipping-out/
• http://martinfowler.com/bliki/FeatureToggle.html
• http://blog.disqus.com/post/789540337/partial-deployment-with-feature-switches
• http://codeascraft.com/2011/02/04/how-does-etsy-manage-development-and-operations/

Feature Flags in Bandiera

In Bandiera there are four classes of feature flags - 'basic', 'user group', 'percentage' and 'date bound'...

Basic Feature Flags

Basic feature flags are binary operators that have no special configuration logic (i.e. the 'User Groups' fields in the edit form are blank). In these features their active state translates directly into their enabled state when your clients come to ask if a feature should be enabled or disabled, (i.e. if active is 'on', enabled will be 'true'; and if active is 'off', enabled will be 'false').

User Group Feature Flags

A 'user group' feature flag is one where one or both of the fields in the 'User Groups' section of the edit form has some values entered in them (these flags will also have a tick in the 'User Groups' column on the Bandiera home page). In these features, the active state acts as follows:

• active is 'on' - consider the user group settings before responding with an enabled state (on a per-request basis).
• active is 'off' - the enabled state will always be 'false'.

If the active state is 'on', all API or client requests for the enabled state should also supply a user_group parameter when asking if a feature flag is enabled or not - if this parameter is not passed through, it is most likely the enabled state will always be false^†,††. Please consult the documentation for your client library as to how to pass this value through, or the API Documentation if you are using the API directly.

Exact Match List

The User Groups 'Exact Match List' is a pretty simple thing - in the feature flag edit form there is a text box for you to enter the names of your user groups that you would like to enable this given feature flag for (one user group per-line). If your client or API request passes in one of these user groups (as the user_group parameter), the enabled value will be 'true'.

NOTE: You are allowed to enter blank lines into the Exact Match List in order to make a long list easier to scan read - these will be ignored when matching the user_group parameter against your list.

Regular Expression

The User Groups 'Regular Expression' allows you to specify a regular expression to match against the incoming user_group parameter. If the regular expression matches the user_group, then the enabled value will be true.

i.e. If you have a regular expression of '.+_admin', then anything that ends in '_admin' will match - e.g. 'super_admin', 'user_admin', 'content_admin' etc. etc.

Mixing Exact Matches and Regular Expressions

With the User Groups feature, you can use an Exact Match List or a Regular Expression, or a combination of both, it's up to you. But it is worth noting that if either the Exact Match List or the Regular Expression matches the incoming user_group parameter, enabled will return 'true' (so it's essentially OR logic).

How to Use User Groups

There is no strict or prescribed way in which you should use User Groups within your applications - it's really up to you to decide what is most appropriate for you, but here are a couple of ways in which we have used/tested this feature:

1. Using a user role (or authorisation group) from within your application - i.e. 'Editor', 'Publishing Manager', 'Admin' - this allows you to expose new functionality to a defined group of users before rolling them out to the whole user base^†††.
2. Using a whitelist of user emails (Exact Match List) - this allows you to expose new functionality to a select group of users before rolling out to the whole user base.
3. Using a Regular Expression to match user emails (i.e. '[email protected]') - this allows all users with a [email protected] user email address to see a new feature before it's rolled out to the whole user base.

Percentage Feature Flags

A 'percentage' feature flag is one where the drop-down field in the 'Percentage of Users' section of the edit form has any value selected (these flags will also have a tick in the 'User %' column on the Bandiera home page). In these features, the active state acts as follows:

• active is 'on' - consider the percentage settings before responding with an enabled state (on a per-request basis).
• active is 'off' - the enabled state will always be 'false'.

If the active state is 'on', all API or client requests for the enabled state should also supply a user_id parameter when asking if a feature flag is enabled or not - if this parameter is not passed through, it is most likely the enabled state will always be false^††. Please consult the documentation for your client library as to how to pass this value through, or the API Documentation if you are using the API directly.

How to Use Percentage Feature Flags

Like the User Group flags, there is no real prescribed way in which you should use Percentage flags within your applications. The way we have used them is when we have a new feature that relies on a new piece of infrastructure or service, we have progressively enabled the new feature to our users, checking the load and response times on the new component as we go - i.e. start at 10% then check everything is ok after an hour or so, increase the percentage up to 20% do the same again and repeat until we are at 100% of the user base and all systems are stable.

Using Both User Groups and Percentages Within a Feature Flag

With Bandiera you are not limited to only using User Group or Percentage based flags - you can combine them in order to display new features to known users (via user group matching) and a selection of the rest of your user base (via percentages).

The way in which combining these two options work is that Bandiera first checks the user_group passed through to the API, if this matches any of the user group options set, the enabled state will be true/on; if none of the user group options matches, and a percentage option has been set, the user_id passed to the API is considered and if this user falls into the set percentage, the enabled state will be true/on, otherwise it will be false/off.

Obviously if the active state on the flag is false/off, the feature will always return a enabled state of false/off.

Date Bound Feature Flags

A 'date bound' feature flag is one where both of the fields in the 'Date Rage' section of the edit form have been filled in (these flags will also have a tick in the 'Date Range' column on the Bandiera home page). In these features, the active state acts as follows:

• active is 'on' - consider if the current date and time fall within the range provided before responding with an enabled.
• active is 'off' - the enabled state will always be 'false'.

If using 'date bound' flags, it is important to note that all date/time values stored within the application, and used during calculations will be in the time zone of the server which is running Bandiera. For example, if you use the default Docker image that comes with Bandiera, your Bandiera instance will use UTC +0000 for all dates. This means you must adjust your ranges to account for your local time zone offset e.g. if you were creating a flag to turn on at 2017-05-02 00:01 +0100 your flag's start date would need to be 2017-05-01 23:01 +0000.

How to Use Date Bound Feature Flags

Like the other flag types, there is no real prescribed way in which you should use Date Bound flags within your applications. These types of flags have been used by the UK Parliament to enable additional features around general elections and other constitutional events.

Using Dates with User Groups or Percentages Within a Feature Flag

With Bandiera, you are free to use Dates with both User Groups or Percentages.

The way in which combining options works is that Bandiera first will check if the User Group or Percentage rules are passing as enabled. Then, providing the current date/time is in the date range of the flag, enabled is passed as true. If the current date/time falls outside of our allowed range, enabled is set to false.

Obviously if the active state on the flag is false/off, the feature will always return a enabled state of false/off.

Glossary

• active - A feature flags active state defines whether a flag is 'active' or not and has the potential to be enabled - i.e. if a flag is not active, it's enabled state will always be 'false' or 'off'. Think of it as a kill-switch for your feature flags.
• enabled - A feature flags enabled state dictates what your applications should be using to decide whether to show a feature to a user or not. This is a simple boolean value (true/false) that will be returned via the API endpoints.

---

^† This is not strictly correct as it is possible for you to configure a regular expression user group that matches an empty string or no value - but if you do that, it's your choice...

^†† If you're using a combination of both 'user groups' and 'percentage' options on a flag, you could still have a feature enabled if only one of the params (user_group and user_id) is passed as either the 'user group' or 'percentage' conditions could be met.

^††† This almost sounds like Bandiera 'could' be used as an authorisation framework within an application - this would be a bad idea^TM and not a use case we'd support...