Meta description attribute for features

[connorwarnock]

We hardcode defaults for all features in the app in a config file to act as documentation for all existing toggles. And while the name is usually descriptive ('new_dashboard'), it's usually short and sweet. It'd be useful to have a meta attribute for a feature to describe the feature in more detail (intended to help other devs / non-technical admins fully understand a feature).

And while it's definitely possible to put this meta description in a readme, readme's aren't easily accessible to non-technical admin vs a dashboard like Flipper UI.

Example:

$flipper[:new_dashboard].meta = 'The new user dashboard layout including the a redesigned profile section.'

[jnunemaker]

The biggest thing for this is persistence. Right now we only persist the name of the feature. Part of me wonders if we need to persist anything. Perhaps we could go the same route as groups and just register features with name, description and anything else needed.

The only downside is that the flipper-ui would always need to be mounted from the same app as where the groups and features are registered, but that seems fine. Anyone have any thoughts on this?

[rsanheim]

I think this would be useful for GitHub's use of flipper right now. Having a description field we could throw arbitrary markdown into would be very nice.

[gdavison]

We're using https://github.com/paybyphone/flipperdotnet from .Net code, so obviously we can't mount the UI from the app. Though we're probably the only people using it :)

[jnunemaker]

@gdavison yeah I'm kind of leaning toward the "persist all this interesting metadata the whole way down" path right now, but I've been thinking through how to allow doing that, without forcing it. I think as long as only name/key is required to use flipper then what we could do is perhaps add some new methods for creating/updating a feature with more meta data (ie: description, which gates can be used, etc.).

[rmosolgo]

Thanks for the great gem! I was slow to see the light on feature flagging but I'm coming around at last.

Another kind of metadata I'd like is a description of various actors. For example, our application is really dependent on our client's hardware configuration (label printers hooked up to USB, which we communicate with via a natively-installed webservice on localhost, it's a nightmare).

We're currently rolling out an upgrade to how we communicate with the printers, but some small number of users are reporting bugs in the new implementation. So, we're using a flag for this new code, slowly testing it in some cases, and hopefully (eventually), turning it on by default, but blacklisting some users to stay on the old implementation.

I'd love to able to add a description to specific actors, for example:

That way, we could look back recall why certain people are getting certain flags!

[jnunemaker]

@rmosolgo What we do at github for that is to create an audit log per feature (in our custom UI). We hook into the ActiveSupport notification events and create audit log entries when things are enabled/dsiabled. Our custom UI then shows those when you are viewing a feature. I'd like to have some way of doing this for flipper in general as well.

I think the key would be to allow passing who and why to enable/disable and then having a format per adapter to store those. It is most likely a decent amount of work, but definitely something I would like to see at some point.

I'm currently spending some time on an alternate idea for adapters that is more key/value style. That would allow for storing random meta data along with features (like disabled gates, descriptions, etc.). It could allow for storing a message like this as well. The branch is backwards compatible kv. I need to write up somewhere here what I'm trying to do with that branch. I currently use trello for personal todo's so I've got a bunch in there, but it really should be in this repo somewhere.

[rmosolgo]

Thanks for the info, that sounds just like what I'm looking for! I'll keep an eye on that branch.

Now ... if only there was some kind of ... built-in trello in github where we could keep our ... projects 😆

[jnunemaker]

@rmosolgo wow, that is such a solid and a great point! I nearly did that by enabling projects for this repo before it was launched, but quickly realized that this is a public repo and that would be a bad idea, thus trello. I'll try to move things to projects here soon and get more written up so people have an idea of direction, even if it is happening slowly.

[rmosolgo]

I don't use projects either ... just wanted to crack a joke :P

[jnunemaker]

@rmosolgo are you using flipper in production? At planning.center?

[rmosolgo]

Yes, several of our teams are using it for their apps!

Actually I'm a late adopter -- I held off for a long time because I was afraid of "littering" the code with conditionals. Turns out that didn't happen, and now I'm a big fan of this technique. I use it for things other than new features too, for example, we have an external service that occasionally caused us slow-down (and the latency was during the SSL handshake, I couldn't find a timeout that would actually prevent it!), so now our integration is behind a "feature flag" which any staff member can flip as needed. Very nice!

[jnunemaker]

@rmosolgo I added an auditing issue which should help with your problem. I also created a project for v2 adapters.

[jnunemaker]

@rmosolgo also, I forgot to respond to your comment: AWESOME! I'm glad you've found it useful (and others at work). I love the idea of using flipper as an on/off switch for functionality. We've done that in places at GitHub as well. It might be worth looking into resilient, my circuit breaker gem, as a way to automatically turn off a feature that is struggling for a period of time as well. It helps avoid the human intervention when possible.

[rmosolgo]

Yes, resilient is exactly the thing! But, if I install that ... what would I do all day? 😆

(cc @jakegavin, this could come in handy for integrations!)

[mgodwin]

Just wanted to chime in and throw in some support for this feature request - often having a description for a feature toggle name is super useful information in a bigger company (just look at the chrome://flags page!) - so having some way to surface this information would be great.

I spent a little while today looking into what it would take to implement this as a monkey patch and it's a bit tricky 😅. I definitely want to avoid maintaining our own fork if we can avoid it, so probably just going to go the route of having a yaml file that contains some of this metadata for the time being.

Also, another piece of useful metadata is what type of actor the feature targets - since some features may be turned on for users, but not projects for example (depending on your domain).

---

I'd love to help out with this, and I think persisting this additional metadata via the adapter is probably a fine approach. It sounds like that was maybe the route you were leaning towards @jnunemaker ? Did this kind of stall out?

Thanks for the great gem!

[jnunemaker]

@mgodwin if it were easy it would be done! 😆 I laugh only because I keep hoping someday someone will drop a brilliant idea in here that I haven't thought of. I totally agree that we do need meta data store. I was thinking the switch to key/value adapters #163 could then serialize opaque blobs per feature which would allow for meta data to be serialized. I can't quite make up my mind on the key/value switch #163 and that is what is blocking this. I need to sit down and list the blockers with pros/cons and make a decision, but haven't made time. Whatever the storage is for the meta data I definitely want it in the adapter and not in ruby land, especially with the work I've been doing on https://flippercloud.io.

Also, another piece of useful metadata is what type of actor the feature targets - since some features may be turned on for users, but not projects for example (depending on your domain).

This is something that you want configured for the feature? Like this feature can only be enabled for this type? I could see something like that slipping into core for sure.

[jnunemaker]

@mgodwin also I just saw the thank you from you. So kind! I really appreciate comments like that.

[jaxn]

I am leaning towards putting the metadata in a separate table/model so that it really fits each application's needs. I wonder if instead of trying to have a flexible metadata system in Flipper itself, there could just be an option to add a metadata model as a has_one and then UI be somewhat aware of the potential availability of a metadata relationship. Maybe that related model is expected to have name and description attributes, but then others can be added as needed by the specific application's needs.

Somewhat similar to how Devise let's you set the model that will act as current_user.

My thinking is that the metadata is generally useful for the UI, but that each application may have other uses for things like additional boolean fields or type columns or whatever.

In our specific example, we sometimes expose feature flags to our end users in a "labs" section of our app. We will add a labs? boolean and when that is true, our Labs page will include the name, description, and a user-controllable toggle. We also tend to have account-level and user-level features. Sometimes a feature can be both. So we will add metadata booleans for those as well.

Flipper UI would then be able to display the name and description, but we would be able to have additional fields as needed for our application. A sample migration for the new model might be something like:

class CreateFlipperMeta < ActiveRecord::Migration
  def change
    create_table :flipper_metas do |t|
      # required fields
      t.references :flipper_features, foreign_key: true, null: false
      t.string :name, null: false
      t.string :description
      # for my use case
      t.boolean :labs_enabled, default: false, null: false
      t.string :labs_description
      t.boolean :user_feature, default: false, null: false
      t.boolean :account_feature, default: false, null: false
    end
  end
end

Anyway, just an idea for another way to approach this problem. I'm going to be hacking together a FeatureMeta model today for our application. If there is interest in this method, I'd be happy to take a stab at a PR that makes Flipper meta-aware and docs on the convention to follow.

[mgodwin]

I ended up writing a monkey patch to extend the Flipper UI to support this, which ended up being quite a bit easier than I anticipated. Some beautifully named methods in there 💯! We use a YAML file to store our metadata, which works pretty well for us right now, and allows us to synchronize feature lists across our different environments.

I also wanted to mention that I found with the AR adapter, we're also storing the created_at time (since AR does that for you automatically), which is pretty nice since you can see how long a feature flag has been around (helpful to see what flags were forgotten about). I decided to surface that information as well which nets me with something like this:

I look forward to maybe a more robust solution in the future, but nice to know there's some alternative approaches!

[jaxn]

@mgodwin is your monkey patch posted anywhere? I'd be interested in seeing what you did.

[mgodwin]

Sorry, I should have posted this a long time ago. Here's a gist you can use if you'd like to patch up your flipper to include this info.

Be wary that due to the fact that the original code isn't very extendable, I had to copy the implementation of a few methods & the view into the monkey patch. So if you update the gem at some point in the future this could break spectacularly! For us, the potential cost was worth it - it's not terribly complex and modifications in the future should be pretty easy.

Hope it helps!

[juanroldan1989]

Hello folks! I've added a PR #461 to facilitate adding descriptions to features, clarifying their goals/reaches within a platform.

Please feel free to make any suggestions! Cheers 🚀

[michaelglass]

this has been released, should the issue be closed?

[jnunemaker]

This does work with UI so I'll close. Originally I envisioned it apart of the feature storage but what we have is good enough for now.