Nimbus Features - rajparad/firefox-ios GitHub Wiki

What is a feature?

A feature, in Nimbus, is a configuration that outlines a set of properties that define the experimentable aspects of a feature. Each feature should be distinct, and standalone from other features.

How it works

The Feature Manifest Language file

Nimbus works by outlining available features in the nimbus.fml.yaml file. This file has three main sections:

• about - identifying the client for Nimbus
• channels - outlining the available channels for building/setting defaults for
• include - outlining the various features to include in the file at build time

Features

Feature files are found in the nimbus-features directory from the root of the repo. For ease of working & maintaining features, each feature should be placed in its own file. Each feature file is composed of several sections:

Section	Optional	Description
features	No	Contains the feature in the file
objects	Yes	Outlines the custom objects for the specific feature
enums	Yes	Outlines the custom enums for the specific feature

If objects or enums don't contain anything, they may be omitted from the file.

When creating a new feature, please use the iOSNimbusFeatureUtility.

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.

Removing a feature

This couldn't be simpler.

1. Go to the nimbus-features folder and remove the .yaml file of the feature in there
2. run sh iOSNimbusFeatureUtility.sh --update at the top level of the repo.