Promotions

Promotions copy definitions from one set to another, so you can move work along release lanes like dev, staging, and production.

Pre-requisites#

Promotions only apply to projects that use sets. Each lane is modeled as its own set, for example dev, staging, and production, each owning its own attributes, segments, features, targets, and tests.

module.exports = {
  sets: true,
  tags: ['all'],
}

Previewing a promotion#

The promote command previews what would be copied from one set to another. Nothing is written to disk until you ask for it:

$ npx featurevisor promote --from=dev --to=staging

This shows the definitions that would be created or updated in the destination set. When you promote a feature, Featurevisor also brings along its dependencies, like the segments and attributes it references.

To include unchanged entries in the preview:

$ npx featurevisor promote --from=dev --to=staging --showUnchanged

Applying a promotion#

Pass --apply to write the destination files:

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

Filtering features#

Filters choose the initial features for a promotion. Featurevisor then includes their complete dependency closure, including required features, exclusion groups, segments, nested segments, attributes, schemas, and relevant tests.

To promote everything needed to build one target's datafile, pass the source target key:

$ npx featurevisor promote --from=dev --to=staging --target=web

This uses the target's tag or tags, includeFeatures, and excludeFeatures selectors with the same semantics as a datafile build. It also promotes the target definition itself. Target context can simplify the eventual datafile, but promotion keeps the full definitions needed by the selected features.

To select features carrying a tag:

$ npx featurevisor promote --from=dev --to=staging --tag=web

You can also select features by key using glob patterns:

$ npx featurevisor promote --from=dev --to=staging --includeFeatures="checkout*"

To start with all features and exclude matching keys:

$ npx featurevisor promote --from=dev --to=staging --excludeFeatures="experimental*"

Filters can be combined. Positive selectors such as --target, --tag, and --includeFeatures use AND semantics. --excludeFeatures is applied last and takes precedence. Dependency closure may add required features or exclusion group members even when they do not match the initial filters.

If the final initial selection contains no features, the command fails so the mistake is visible early. Pass --allowEmpty if an empty result is acceptable. An unknown --target or --tag always fails and lists the available source values.

Conflicts#

When a definition already exists in the destination set with different values, that is a conflict. The --conflicts option controls how conflicts are resolved:

• source: the source set wins and overwrites the destination (default)
• destination: the destination keeps its existing values
• fail: stop with an error instead of overwriting

$ npx featurevisor promote --from=dev --to=staging --conflicts=fail

Protecting definitions during promotion#

By default, definitions can update their matching destination definitions. Set promotable: false on either side to preserve an existing destination definition during promotion. If the definition does not exist in the destination yet, it is created and keeps the field for later promotions.

This works on whole definitions, like a feature:

description: Checkout flow
promotable: false
tags:
  - all
rules:
  - key: everyone
    segments: '*'
    percentage: 100

Rules are stricter. A source rule with promotable: false is omitted, while an existing destination rule with promotable: false is preserved:

description: Checkout flow
rules:
  - key: internal-testing
    promotable: false
    segments: internal
    percentage: 100
  - key: everyone
    segments: '*'
    percentage: 50

The same top level behavior is supported on attributes, segments, groups, schemas, targets, and test specs.

Allowed promotion flows#

By default, any set can be promoted to any other set. To restrict which promotions are allowed, define promotionFlows in your configuration:

module.exports = {
  sets: true,
  tags: ['all'],
  promotionFlows: [
    { from: 'dev', to: 'staging' },
    { from: 'staging', to: 'production' },
  ],
}

With the configuration above, promote --from=dev --to=production fails because that flow is not listed. Promoting from dev to staging, or from staging to production, is allowed.

Audit files#

Pass --audit to write a record of a promotion. This is useful alongside --apply to keep a trail of what changed:

$ npx featurevisor promote --from=dev --to=staging --apply --audit=markdown

Audit files are written under .featurevisor/promotions/. Use --audit=json for machine-readable output, or --audit=markdown for a human-readable summary.

Learn more#

• Sets: split a project into independent trees
• Environments: different rules per feature within a single tree
• State files: where Featurevisor keeps generated state