Skip to content

Commit 3f14b63

Browse files
amerjusupovicjimmyca15
amerjusupovic
and
jimmyca15
authored
Update README file for variants (#264)
* update readme with variants, first draft * small summary revisions * fix wording of summary * fix code description * Apply suggestions from code review Co-authored-by: Jimmy Campbell <jimmyca@microsoft.com> * revisions * PR revisions, describe Allocation properties, fix descriptions and titles * clarify configurationvalue possible values * clarify seed description * remove all mentions of On filter * fix example for override, clarify allowing no configurationvalue or reference * change statusoverride example * Apply suggestions from code review Co-authored-by: Jimmy Campbell <jimmyca@microsoft.com> * revisions to summaries, fix allocation table --------- Co-authored-by: Jimmy Campbell <jimmyca@microsoft.com>
1 parent 17d6202 commit 3f14b63

File tree

1 file changed

+171
-0
lines changed

1 file changed

+171
-0
lines changed

‎README.md

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@ Here are some of the benefits of using this library:
3232
* [Built-in Feature Filters](#built-in-Feature-Filters)
3333
* [Targeting](#targeting)
3434
* [Targeting Exclusion](#targeting-exclusion)
35+
* [Variants](#variants)
3536
* [Caching](#caching)
3637
* [Custom Feature Providers](#custom-feature-providers)
3738

@@ -139,6 +140,25 @@ A `RequirementType` of `All` changes the traversal. First, if there are no filte
139140

140141
In the above example, `FeatureW` specifies a `RequirementType` of `All`, meaning all of it's filters must evaluate to true for the feature to be enabled. In this case, the feature will be enabled for 50% of users during the specified time window.
141142

143+
### Status
144+
145+
146+
`Status` is an optional property of a feature flag that controls how a flag's enabled state is evaluated. By default, the status of a flag is `Conditional`, meaning that feature filters should be evaluated to determine if the flag is enabled. If the `Status` of a flag is set to `Disabled` then feature filters are not evaluated and the flag is always considered to be disabled.
147+
148+
149+
```
150+
"FeatureX": {
151+
"Status": "Disabled",
152+
"EnabledFor": [
153+
{
154+
"Name": "AlwaysOn"
155+
}
156+
]
157+
}
158+
```
159+
160+
In this example, even though the `AlwaysOn` filter would normally always make the feature enabled, the `Status` property is set to `Disabled`, so this feature will always be disabled.
161+
142162
### Referencing
143163

144164
To make it easier to reference these feature flags in code, we recommend to define feature flag variables like below.
@@ -636,6 +656,157 @@ When defining an Audience, users and groups can be excluded from the audience. T
636656

637657
In the above example, the feature will be enabled for users named `Jeff` and `Alicia`. It will also be enabled for users in the group named `Ring0`. However, if the user is named `Mark`, the feature will be disabled, regardless if they are in the group `Ring0` or not. Exclusions take priority over the rest of the targeting filter.
638658

659+
## Variants
660+
661+
When new features are added to an application, there may come a time when a feature has multiple different proposed design options. A common solution for deciding on a design is some form of A/B testing, which involves providing a different version of the feature to different segments of the user base and choosing a version based on user interaction. In this library, this functionality is enabled by representing different configurations of a feature with variants.
662+
663+
Variants enable a feature flag to become more than a simple on/off flag. A variant represents a value of a feature flag that can be a string, a number, a boolean, or even a configuration object. A feature flag that declares variants should define under what circumstances each variant should be used, which is covered in greater detail in the [Allocating a Variant](./README.md#allocating-a-variant) section.
664+
665+
``` C#
666+
public class Variant
667+
{
668+
/// <summary>
669+
/// The name of the variant.
670+
/// </summary>
671+
public string Name { get; set; }
672+
673+
/// <summary>
674+
/// The configuration of the variant.
675+
/// </summary>
676+
public IConfigurationSection Configuration { get; set; }
677+
}
678+
```
679+
680+
### Getting a Feature's Variant
681+
682+
A feature's variant can be retrieved using the `IVariantFeatureManager`'s `GetVariantAsync` method.
683+
684+
``` C#
685+
…
686+
IVariantFeatureManager featureManager;
687+
…
688+
Variant variant = await featureManager.GetVariantAsync(MyFeatureFlags.FeatureU);
689+
690+
IConfigurationSection variantConfiguration = variant.Configuration;
691+
692+
// Do something with the resulting variant and its configuration
693+
```
694+
695+
### Setting a Variant's Configuration
696+
697+
For each of the variants in the `Variants` property of a feature, there is a specified configuration. This can be set using either the `ConfigurationReference` or `ConfigurationValue` properties. `ConfigurationReference` is a string path that references a section of the current configuration that contains the feature flag declaration. `ConfigurationValue` is an inline configuration that can be a string, number, boolean, or configuration object. If both are specified, `ConfigurationValue` is used. If neither are specified, the returned variant's `Configuration` property will be null.
698+
699+
```
700+
"Variants": [
701+
{
702+
"Name": "Big",
703+
"ConfigurationReference": "ShoppingCart:Big"
704+
},
705+
{
706+
"Name": "Small",
707+
"ConfigurationValue": {
708+
"Size": 300
709+
}
710+
}
711+
]
712+
```
713+
714+
### Allocating a Variant
715+
716+
The process of allocating a variant to a specific feature is determined by the `Allocation` property of the feature.
717+
718+
```
719+
"Allocation": {
720+
"DefaultWhenEnabled": "Small",
721+
"DefaultWhenDisabled": "Small",
722+
"User": [
723+
{
724+
"Variant": "Big",
725+
"Users": [
726+
"Marsha"
727+
]
728+
}
729+
],
730+
"Group": [
731+
{
732+
"Variant": "Big",
733+
"Groups": [
734+
"Ring1"
735+
]
736+
}
737+
],
738+
"Percentile": [
739+
{
740+
"Variant": "Big",
741+
"From": 0,
742+
"To": 10
743+
}
744+
],
745+
"Seed": "13973240"
746+
},
747+
"Variants": [
748+
{
749+
"Name": "Big",
750+
"ConfigurationReference": "ShoppingCart:Big"
751+
},
752+
{
753+
"Name": "Small",
754+
"ConfigurationValue": "300px"
755+
}
756+
]
757+
```
758+
759+
The `Allocation` setting of a feature flag has the following properties:
760+
761+
| Property | Description |
762+
| ---------------- | ---------------- |
763+
| `DefaultWhenDisabled` | Specifies which variant should be used when a variant is requested while the feature is considered disabled. |
764+
| `DefaultWhenEnabled` | Specifies which variant should be used when a variant is requested while the feature is considered enabled and no variant was allocated to the user. |
765+
| `User` | Specifies a variant and a list of users for which that variant should be used. |
766+
| `Group` | Specifies a variant and a list of groups the current user has to be in for that variant to be used. |
767+
| `Percentile` | Specifies a variant and a percentage range the user's calculated percentage has to fit into for that variant to be used. |
768+
| `Seed` | The value which percentage calculations for `Percentile` are based on. The percentage calculation for a specific user will be the same across all features if the same `Seed` value is used. If no `Seed` is specified, then a default seed is created based on the feature name. |
769+
770+
In the above example, if the feature is not enabled, `GetVariantAsync` would return the variant allocated by `DefaultWhenDisabled`, which is `Small` in this case.
771+
772+
If the feature is enabled, the feature manager will check the `User`, `Group`, and `Percentile` allocations in that order to allocate a variant for this feature. If the user being evaluated is named `Marsha`, in the group named `Ring1`, or the user happens to fall between the 0 and 10th percentile calculated with the given `Seed`, then the specified variant is returned for that allocation. In this case, all of these would return the `Big` variant. If none of these allocations match, the `DefaultWhenEnabled` variant is returned, which is `Small`.
773+
774+
Allocation logic is similar to the [Microsoft.Targeting](./README.md#MicrosoftTargeting) feature filter, but there are some parameters that are present in targeting that aren't in allocation, and vice versa. The outcomes of targeting and allocation are not related.
775+
776+
### Overriding Enabled State with a Variant
777+
778+
You can use variants to override the enabled state of a feature flag. This gives variants an opportunity to extend the evaluation of a feature flag. If a caller is checking whether a flag that has variants is enabled, then variant allocation will be performed to see if an allocated variant is set up to override the result. This is done using the optional variant property `StatusOverride`. By default, this property is set to `None`, which means the variant doesn't affect whether the flag is considered enabled or disabled. Setting `StatusOverride` to `Enabled` allows the variant, when chosen, to override a flag to be enabled. Setting `StatusOverride` to `Disabled` provides the opposite functionality, therefore disabling the flag when the variant is chosen. A feature with a `Status` of `Disabled` cannot be overridden.
779+
780+
```
781+
"Allocation": {
782+
"Percentile": [{
783+
"Variant": "On",
784+
"From": 10,
785+
"To": 20
786+
}],
787+
"DefaultWhenEnabled": "Off",
788+
"Seed": "Enhanced-Feature-Group"
789+
},
790+
"Variants": [
791+
{
792+
"Name": "On",
793+
"ConfigurationValue": true
794+
},
795+
{
796+
"Name": "Off",
797+
"ConfigurationValue": false,
798+
"StatusOverride": "Disabled"
799+
}
800+
],
801+
"EnabledFor": [
802+
{
803+
"Name": "AlwaysOn"
804+
}
805+
]
806+
```
807+
808+
In the above example, the feature is enabled by the `AlwaysOn` filter. If the current user is in the calculated percentile range of 10 to 20, then the `On` variant is returned. Otherwise, the `Off` variant is returned and because `StatusOverride` is equal to `Disabled`, the feature will now be considered disabled.
809+
639810
## Caching
640811

641812
Feature state is provided by the IConfiguration system. Any caching and dynamic updating is expected to be handled by configuration providers. The feature manager asks IConfiguration for the latest value of a feature's state whenever a feature is checked to be enabled.

0 commit comments

Comments
 (0)