Needs docs for feature flag priority

[Deryck Hodge]

I added a feature flag today for timeout, and while I get the idea of "priority" in the abstract, I wasn't sure what value to choose. jml did a review of this for me and also had no idea what value to use. I went with 1, which seemed a nice default, and mthaddon got an OOPS because priority must be unique across all flags. This further complicates my understanding of this attribute of a feature flag. :-)

So we need some docs about what this attribute means, how it's used, and what values we should assign.

[Robert Collins (lifeless)]

Its described in the docstrings and the wiki. Perhaps you'd like to
improve those on the wiki ? :)

Higher priority wins.

[Deryck Hodge (deryck)]

Robert, I don't mind updating the docstrings or wiki. I don't get it, though. I've heard "higher priority wins" before and it's not enough to help me understand it. Currently, people are just incrementing the priority number with each new flag. So it's better to say "newest flag wins," but why do I care? Why are the flags fighting? What flexibility does this add? How should we design our flags with this priority in mind?

I could make educated guesses on those questions based on using them and talking to Martin, but I think it makes sense to document this better. It just came up again with Graham asking me today.

Cheers,
deryck

[Robert Collins (lifeless)]

On Fri, Nov 5, 2010 at 4:49 AM, Deryck Hodge <email address hidden> wrote:
> Robert, I don't mind updating the docstrings or wiki.  I don't get it,
> though.  I've heard "higher priority wins" before and it's not enough to
> help me understand it.  Currently, people are just incrementing the
> priority number with each new flag.  So it's better to say "newest flag
> wins," but why do I care?  Why are the flags fighting?  What flexibility
> does this add?  How should we design our flags with this priority in
> mind?

Great questions - and I wouldn't have thought to answer them all. So here goes.
We have scopes, rules and flags.
Flags are set from a rule.
The rule that determines the value of a flag is:
"The highest priority rule for that flag whose scope matches"

As an example consider two rules for timeouts:
hard_timeout team:admins 1 18000
hard_timeout default 0 15000

Asking for the flag 'hard_timeout' will cause the feature controller
to loop on these two rules - first the team:admins one, then the
default one. Any request for which the logged in user is an admin will
match the higher priority rule, all other requests will fall down to
the next rule.

Hope that helps.
-Rob

[Deryck Hodge (deryck)]

Makes perfect sense now, thanks! I'll update docstrings and the wiki page where appropriate tomorrow, and consider this bug closed.

Cheers,
deryck

[Martin Pool (mbp)]

I filed <https://bugs.launchpad.net/launchpad/+bug/719186> saying that making people assign nonoverlapping integers themselves is a bit crude. Maybe someone can add an ajaxy drag and drop interface or suggest something better.

Also <https://dev.launchpad.net/Foundations/FeatureFlags> now has developer-oriented docs including Robert's example; suggestions for what more to add would be welcome.