-
Notifications
You must be signed in to change notification settings - Fork 2.9k
Feature Flags
In the Firefox iOS codebase, we define a feature flag as a variable, inside a feature, that controls the status of the feature in the application.
Feature flags should logically be part of their own features, even if that's the only variable in that feature. - ie. Should not be part of a generalAppFeature, or a featureFlagFeature.
Feature flags are all controlled by the FeatureFlagManager
singleton. To access the singleton, you must make a class conform to the FeatureFlaggable
protocol, which will give access to the featureFlags
variable.
class BibimbapViewModel: FeatureFlaggable {
var isNewMenuAvailable: Bool {
return featureFlags.isFeatureEnabled(.newBibimbapMenu, checking: .buildOnly)
}
}
Name | Description | User Togglable |
---|---|---|
Core | Core features are features that are used for developer purposes and are not directly user impacting. | No |
Nimbus | A nimbus feature is a feature whose configuration comes from Nimbus. | Possibly |
The vast majority of feature flags should be Nimbus flags, rather than Core flags.
Interface | Purpose |
---|---|
isCoreFeatureEnabled(...) |
Checking where a Core feature is enabled. |
isFeatureEnabled(...) |
Checking whether a boolean based Nimbus feature is enabled. |
getCustomState<T>(...) |
Checking the status of a non-boolean based Nimbus feature. |
set(...) |
Saving a boolean based Nimbus feature user preference to UserDefaults. |
set<T: FlaggableFeatureOptions>(...) |
Saving a non-boolean based Nimbus feature user preference to UserDefaults. |
One of the complexities of feature flags is that while Nimbus may have a default, a user may turn something off. Regardless of whether or not the user is in an experiment, their preferences should be respected. To accomplish this, the previously listed interfaces that check a feature status include a specific checking
parameter. This has three options which should cover 100% of use cases for needing to check the status of a feature.
-
buildOnly
- this will only check Nimbus configuration for status -
userOnly
- this will check UserDefaults to see if the user has a preference. If they do, that is what will be returned. If they do not, then the Nimbus configuration is queried for status -
buildAndUser
- this will a mix of both.
To add a feature to Nimbus, please read Nimbus Feature. Once this is done, add a variable to that feature named something indicative of a status. Here is an example of what that might look like
...
isEnabled:
description: >
Whether or not the feature is enabled.
type: Boolean
default: false
After the changes have been made, be sure to build the application
Say you wanted to add a flag that controlled whether a user saw an old menu or a new menu. To add the flag in the app (for example, for the newBibimbapMenu
flag), follow these three simple steps:
- Add
case newBibimbapMenu
to theNimbusFeatureFlagID
enum. - Add this new case to the
NimbusFlaggableFeature
struct. a. If the user will have a setting to interact with for the feature, you should add this such that it returns aPrefsKeys.FeatureFlags
key, which you will have to also add. b. If the user doesn't have a setting for the feature, you should add it to thereturn nil
part of the switch statement. - In the
NimbusFeatureFlagLayer
class, you should add a case for your new feature, as well as the function it will call
...
switch featureID {
case .newBibimbapMenu:
return checkBibimbapFeature(for: featureID, from: nimbus)
...
private func checkBibimbapFeature(
for featureID: NimbusFeatureFlagID,
from nimbus: FxNimbus
) -> Bool {
let config = nimbus.features.bibimbapFeature.value()
switch featureID {
case .newBibimbapMenu: return config.newBibimbapMenu
default: return false
}
}
At this point, your work is done and you now have a feature flag that can be checked.
Say you wanted a flag that had more than two options. In our example, there is a morning, afternoon, and evening version of the menu. The complexity in this case is that Nimbus features must be mapped. Improvements to this will be coming in the future, but as of now, here's how to accomplish this.
- Add
case bibimbapMenuVersion
to theNimbusFeatureFlagID
enum. - Add
case bibimbapMenuVersion
to theNimbusFeatureFlagWithCustomOptionsID
enum. - Add this new case to the
NimbusFlaggableFeature
struct. a. If the user will have a setting to interact with for the feature, you should add this such that it returns aPrefsKeys.FeatureFlags
key, which you will have to also add. b. If the user doesn't have a setting for the feature, you should add it to thereturn nil
part of the switch statement. - In the
FlaggableFeatureOptions
file, create an enum for your feature flag, inheriting from String andFlaggableFeatureOptions
.
enum BibimbapMenuVersion: String, FlaggableFeatureOptions {
case morning
case afternoon
case evening
}
- In the
NimbusFeatureFlagLayer
class, you should add a case for your new feature, as well as the function it will call
...
switch featureID {
case .newBibimbapMenu:
return checkBibimbapFeature(for: featureID, from: nimbus)
...
private func checkBibimbapFeature(from nimbus: FxNimbus) -> BibimbapMenuVersion {
let config = nimbus.features.bibimbapFeature.value()
let nimbusSetting = config.bibimbapMenuVersion
switch nimbusSetting {
case .morning: return .morning
case .afternoon: return .afternoon
case .evening: return .evening
}
}
- In the
NimbusFlaggableFeature
class, undergetUserPreference
, you should add your case in the switch:
case .bibimbapMenuVersion:
return nimbusLayer.checkBibimbapFeature().rawValue
- In
NimbusFeatureFlagManager
'sgetCustomState<T>
, add your case to the switch statement.
case .bibimbapMenuVersion: return BibimbapMenuVersion(rawValue: userSetting) as? T
At this point, your work is done and you now have a feature flag that can be checked:
lazy var bibimbapMenuVersion: BibimbapMenuVersion? = featureFlags.getCustomState(for: .bibimbapMenuVersion)
In order to test your feature flag using the app, we now have a Feature Flags
section in our secret settings (tap on the version number in settings 5 times). Scroll down until you see the Feature Flags
cell and tap on it. This setting is only available for developer / beta builds and is hidden from production. The view contains a top portion where you can toggle certain features flags on and off and the bottom contains the current values that the app has.
Debug Menu | Feature Flags Section |
---|---|
How to add a new toggle
- Add the feature flag case to
debugKey
forNimbusFeatureFlagID
and ensure that it returns a string usingrawValue + PrefsKeys.FeatureFlags.DebugSuffixKey
. Cases return adebugKey
that isnil
by default. - Create a new
FeatureFlagsBoolSetting
specific to the feature flag case you want to toggle inFeatureFlagsDebugViewController
. - Add the new setting to
SettingSection
inFeatureFlagsDebugViewController
. - Run the app and navigate to the feature flag debug setting. Confirm that you can now see your new feature flag toggle setting and it works appropriately.
Proposal PR: https://github.com/mozilla-mobile/firefox-ios/pulls?q=is%3Apr+debug+menu+is%3Aclosed+