Skip to content

Commit

Permalink
Document nimbus-fml info command
Browse files Browse the repository at this point in the history
  • Loading branch information
jhugman committed Dec 1, 2023
1 parent 8561e5b commit e771815
Showing 1 changed file with 73 additions and 0 deletions.
73 changes: 73 additions & 0 deletions docs/deep-dives/specifications/fml/fml-cli.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -108,3 +108,76 @@ To help this, the `single-file` command is used to merge all imports and include
```
% nimbus-fml single-file --channel release @mozilla-mobile/firefox-android/fenix/app/nimbus.fml.yaml single-file.fml.yaml
```

## Generating a machine readable overview of a feature

```sh
nimbus-fml info [--channel CHANNEL] [--json] <MANIFEST> [--feature FEATURE]
```

This prints a simplified YAML or JSON representation for each feature. e.g.

```json
{
"file": "https://raw.githubusercontent.com/mozilla-mobile/firefox-android/main/fenix/app/nimbus.fml.yaml",
"features": {
"homescreen": {
"description": "The homescreen that the user goes to when they press home or new tab.",
"types": [
"Boolean",
"HomeScreenSection",
"Map<HomeScreenSection, Boolean>"
],
"hashes": {
"schema": "7a15570b",
"defaults": "423ab0bd"
}
}
}
}
```

The `hashes` object shows truncated SHA256 hashes for:

- the schema (the types, variable names, the enum variants available)
- the defaults (the default values of the feature variables)

Changes in the schema hash might indicate a change in the feature code.
Changes in the defaults hash would indicate a different configuration being used for the same code.

:::info
Changes in the schema hash will almost always be accompanied by a change in the defaults hash, with the exception of changing variable types from
a `String` type to a `string-alias` type (or vice-versa).
:::

The `types` list is a sorted list of the types involved used to define the feature. This list may be used as a proxy for a measure of complexity of the feature configuration space.

In addition, [the feature metadata](/fml/feature-metadata) is also displayed.

If a `--feature` argument is supplied, then restrict the output to just this feature.

If a `--channel` argument is supplied, then use this channel. This will affect the `defaults` hashes.

:::hint Using `info` with JQ
You can use `--json` JQ to output some interesting data:

Get the features for this app:

```sh
nimbus-fml info <INPUT> --json | jq '.features|keys'
```

Get the channels for this app:

```sh
nimbus-fml channels <INPUT> --json
```

Get the hashes for just the `homescreen` feature:

```sh
nimbus-fml info <INPUT> --json | jq '.features.homescreen.hashes'
```
::

`--cache-dir`, `--ref` and `--repo-file` arguments are also supported.

0 comments on commit e771815

Please sign in to comment.