Feature Flags

What is a feature flag?

Is 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.

How feature flags work in Firefox iOS

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)
    }
}

Types of features flags

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.

The FeatureFlagManager interface

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.

How to set up a Feature Flag

Adding a feature to Nimbus

To add a feature to Nimbus, please read Nimbus Feature

Adding a feature flag

Most feature flags

How to use features

Some external documentation on Nimbus features can be found here. However, setting up a new feature in code is fairly simple, if these steps are followed.

1. Use the iOSNimbusFeatureUtility to add a feature
2. Implement a layer translating the feature from FxNimbus to what you need to use.
3. Use the layer in the app appropriately.

The iOSNimbusFeatureUtility

This utility should be used for managing the nimbus.fml.yaml file, and currently provides the ability to add a feature and update the file. To use it, use the following command at the root level of the repository in your terminal. Note that an argument is required.

$ sh iOSNimbusFeatureUtility.sh --argument

Arguments

Argument	Description
--add exampleNameFeature	This creates a feature file named exampleNameFeature.yaml in the nimbus-features directory. It also adds a template to that file for a new feature. exampleName should be camelCase and should have the suffix Feature, also camelCased. This will then also run the --update command, so it's not necessary to run it yourself.
--update	This updates the nimbus.fml.yaml file with the features that currently exist in the nimbus-features directory.

Editing a feature

To edit a feature, open the respective feature's file in the nimbus-features directory, and proceed to edit the feature.

To edit a feature simply means to add or remove a variable, as well as adding or removing objects or enums as necessary.

One current drawback is that the build system knows if there's been a change to the nimbus.fml.yaml file, but doesn't know about changes in files found in the include block. If you make a change and update one of those file, to see these changes reflected in the generated FxNimbus.swift, you must clean and rebuild in Xcode.

Note: The top level feature name should not be changed unless working with a Nimbus engineer to make sure the old name is removed from the database, as this is currently a manual process. This only applies if editing a feature that is also present in the main branch. If you are working on a branch where you are adding a new feature and it has not yet been merged to main, feel free to change the feature name as much as you like.