Featurevisor

Definitions in depth

Environments

Environments give one feature different rules in each place it runs, such as staging and production, and build a datafile for each. They are optional. The default project has none, and every feature has one list of rules.

Environments, sets or neither

Start with neither unless you know you need more:

  • Neither is the default. Each feature has one list of rules and the project builds one set of datafiles. Test changes before they merge, and use a percentage rollout in production.
  • Environments keep the rules for staging and production side by side in each feature file. Choose them when one change should be reviewed for all environments at once.
  • Sets keep a separate tree of definitions per release lane, and changes move from one lane to the next through promotions. Choose them when a lane should be able to differ completely, as described below.

The choice can change later. convert moves a project between the three, and checks that every feature and global variable builds the same.

Add environments

For a new project, start from the example with environments in an empty directory:

Command
npx @featurevisor/cli@latest init --example=with-environments

For an existing project, convert it. Converting lists the environments in the configuration and rewrites your definitions to match:

featurevisor.config.js
module.exports = {
environments: ['staging', 'production'],
}

Leave environments out entirely for a project without them. An empty list fails.

Give each environment its own rules

With environments, rules groups its rule lists by environment. This keeps checkout from the Quick start as it is in production, and fully on in staging:

features/checkout.yml
description: Checkout redesign
bucketBy: userId
rules:
staging:
- key: everyone
conditions: "*"
percentage: 100
production:
- key: netherlands
conditions: netherlands
percentage: 100
- key: everyone
conditions: "*"
percentage: 25
  • A feature that leaves out an environment has no rules there, so it is disabled, though force entries for that environment still apply. An empty list such as staging: [] says the same, unless the environment inherits.
  • A feature may leave out rules altogether, and then has no rules in any environment.
  • force and expose are grouped by environment the same way, and so are a global variable's overrides.
  • Attributes, segments, schemas and targets are shared by every environment.

Build a datafile per environment

Building writes each target's datafile once per environment:

Command
tree datafiles
Output
datafiles
├── REVISION
├── production
│ └── featurevisor-all.json
└── staging
└── featurevisor-all.json

build --environment=staging builds only staging and leaves production untouched, but still moves the shared revision forward. Build every environment before you publish the whole datafiles directory.

Load the right datafile

Each deployment of your application loads its own environment's file, such as production/featurevisor-all.json. The SDK evaluates whatever datafile it is given, and never picks an environment from the context.

features/checkout.yml holds staging rules, everyone at 100%, and production rules, netherlands at 100% and everyone at 25%. The build writes staging/featurevisor-all.json for the staging deployment and production/featurevisor-all.json for the production deployment.

Test and evaluate per environment

Every feature assertion names its environment:

tests/features/checkout.spec.yml
feature: checkout
assertions:
- description: Dutch users, production
environment: production
at: 90
context:
country: nl
expectedToBeEnabled: true
- description: Everyone, staging
environment: staging
at: 90
context:
country: de
expectedToBeEnabled: true

The CLI's runtime commands take the same choice, such as npx featurevisor evaluate --environment=production. See Testing and the CLI.

Add an environment later

A project that has grown can gain an environment without anyone touching their definitions. List it, and say which environment it follows wherever a definition says nothing:

featurevisor.config.js
module.exports = {
environments: ['dev', 'staging', 'production'],
inheritEnvironments: {
dev: { from: 'staging' },
},
}

Lint and tests pass as they did, and the staging and production datafiles stay the same apart from the revision. Each target gains a dev datafile, which matches its staging one until a team writes something for dev.

Without inheritEnvironments, every feature starts disabled in dev. A team that gives its feature rules in dev then finds it still disabled if it depends on a feature nobody else has touched, and a global variable tied to such a feature returns its disabled value.

Each definition decides for itself:

What a definition says for devWhat happens in dev
NothingIt uses what it has for staging
dev: []It has none, and inherits nothing
dev: with entriesIt uses its own

This gives checkout a rule of its own in dev. Only this file changes, so only its owners review it:

features/checkout.yml
# ...
rules:
dev:
- key: netherlands
conditions: netherlands
percentage: 100
staging:
- key: everyone
conditions: "*"
percentage: 100
production:
- key: netherlands
conditions: netherlands
percentage: 100
- key: everyone
conditions: "*"
percentage: 25
  • rules, force, expose and a global variable's overrides each inherit on their own, so this feature still uses any force entries staging has. Write force: { dev: [] } to stop that, or expose: { dev: true } to expose in dev what staging does not.
  • A list replaces the inherited one whole. Nothing is merged.
  • A feature inheriting its rules gives each user the variation it gives them in the other environment, as State files explains.
  • Test assertions do not inherit. Add one that names dev when you want dev checked.
  • An edit to staging reaches dev at the next build, which diff points out.
  • Several environments may inherit from one, as long as that one inherits from nothing.

Production can inherit too

If production inherits from staging, every edit to staging reaches production at the next build. Requiring production refuses this.

To see who has written their own rules for dev, and who still has none:

Commands
npx featurevisor list --features --defined-in=dev
npx featurevisor list --features --not-defined-in=dev

Both also work with --variables, where they read overrides.

Roll out the new environment

Adding dev to the configuration changes no application. Three steps make it live:

  1. Build it in your deployment. A plain npx featurevisor build writes every environment. A script that names each one, such as --environment=staging, needs a line for dev.
  2. Commit its state file. The first build writes .featurevisor/existing-state-dev.json, which git add .featurevisor in Deployment picks up. A workflow that names each file has to add it. Without it, dev still follows staging, but users can switch variations the first time a team writes rules of its own.
  3. Point applications at it. Each deployment running in dev loads dev/featurevisor-all.json, as Load the right datafile shows. Nothing changes for an application until it does.

Check an existing environment

A new dev has nothing relying on it. If dev already exists, a definition that leaves it out is off there today, and a team may depend on that. inheritEnvironments turns that definition on in dev without anyone editing its file. Lint has nothing to report, since nothing is invalid, and diff shows only the change to the configuration.

List what would change before you add the setting:

Commands
npx featurevisor list --features --not-defined-in=dev
npx featurevisor list --variables --not-defined-in=dev

Write dev: [] in each definition that must stay as it is in dev, then add the setting. These lists read rules and overrides. A feature's force and expose inherit too, so check any feature that has them.

Require an environment

Leaving out an environment passes lint, so a feature that forgets production ships disabled there. To make that a choice someone has to write down, list the environment:

featurevisor.config.js
module.exports = {
environments: ['staging', 'production'],
requireRulesIn: ['production'],
requireOverridesIn: ['production'],
}

requireRulesIn applies to each feature's rules, and requireOverridesIn to each global variable's overrides. A definition that writes nothing for production fails lint:

Output
features/checkout.yml
=> Error: Missing rules for required environment "production". Add them, or write "production: []" to keep the feature off there.
Path: rules.production

production: [] satisfies the rule, because writing it is the decision. Archived definitions are exempt. An environment that inherits cannot be required, and the configuration fails if you try.

Switch an existing project

convert changes an existing project's shape, rewriting every definition, test spec, state file and the configuration to match. Give a project without environments staging and production:

Command
npx featurevisor convert --to=environments

It previews by default, and writes only with --apply. Before writing, it checks that a converted copy lints, passes its tests and builds every feature and global variable the same in each environment.

To remove environments, name the one whose behaviour to keep:

Command
npx featurevisor convert --to=flat --keep=production

After applying, add or remove --environment in your commands, and point applications at the datafile paths the preview names. Converting shows what each conversion writes and checks.

Older scaffolds also used tag: all in targets/all.yml. Keep it to include only tagged definitions, or remove it to include everything. Target selection does not depend on environments.

Release lanes with sets

Some teams treat dev, staging and production as separate release lanes rather than environments of one definition. Each lane is a set with its own complete tree, so a feature can differ completely between lanes, and changes move forward only when promoted. The example for this layout keeps its historical name:

Command
npx @featurevisor/cli@latest init --example=environments

It enables sets instead of environments, and uses promotionFlows to keep promotions moving forward one lane at a time:

featurevisor.config.js
module.exports = {
sets: true,
promotionFlows: [
{ from: 'dev', to: 'staging' },
{ from: 'staging', to: 'production' },
],
}

Each lane has its own attributes/, segments/, features/, targets/ and tests/ under sets/<lane>/. Rules are plain lists, because there are no environments. The same feature can be fully on in dev and still off in production:

sets/dev/features/checkoutFlow.yml
description: New checkout flow
bucketBy: userId
rules:
- key: everyone
conditions: "*"
percentage: 100
sets/production/features/checkoutFlow.yml
description: New checkout flow
bucketBy: userId
rules:
- key: everyone
conditions: "*"
percentage: 0

Building writes datafiles/dev/featurevisor-all.json, datafiles/staging/featurevisor-all.json and datafiles/production/featurevisor-all.json. When dev is ready, promote it to staging:

Command
npx featurevisor promote --from=dev --to=staging --apply

promotionFlows rejects promoting straight from dev to production. See Sets and Promotions.

In the example, staging sits between the two: its checkoutFlow is on for the internal segment and off for everyone else.

Three sets read bottom up. In sets/dev, checkoutFlow is on for everyone. In sets/staging, it is on for internal users only. In sets/production, it is off for everyone. Promotions move from dev to staging and from staging to production.

Turn environments into sets

To make an existing project's environments release lanes, convert it:

Command
npx featurevisor convert --to=sets

Each environment becomes a set, and each feature keeps that environment's rules there. convert --to=environments goes back, when the sets share their attributes, segments, schemas and targets. See Turn environments into sets and Go back to environments.

Previous
Tags