Proposal: Introduce a unified configuration option for experimental/preview features

[oleiade]

Summary

This proposal outlines a plan to introduce a single, unified configuration option (e.g., an environment variable K6_FEATURES (only used as example throughout the document, name to be discussed and decided)) to enable and disable all experimental and preview features in k6. This will simplify maintenance, reduce configuration complexity, and improve discoverability for users.

Problem

With the release of k6 v1.0 and our stricter versioning and stability guarantees, we will rely more heavily on experimental features to provide early access to changes and gather user feedback.

Currently, experimental capabilities are enabled in different ways (e.g., special modules, environment variables like for binary provisioning). If we continue this pattern, we risk a proliferation of disparate flags and environment variables.

This leads to several problems:

• Increased Maintenance Burden: Each custom flag needs to be maintained, deprecated, and eventually removed individually.
• Larger Configuration Surface: The number of ways to configure k6 grows, making it harder for users to understand and manage.
• Poor Discoverability: Experimental features are scattered and not easily found by users who might want to test them.

Proposal

We propose introducing a single environment variable to act as a centralized feature flag manager. This variable would accept a comma-separated list of normalized feature names to activate or modify specific behaviors in k6.

The benefits of this approach are:

• Simplified Management: A single option simplifies maintenance for us and usage for our users.
• Centralized Documentation: We can create a single "Experimental & Preview Features" documentation page that explains the system and lists all available feature flags.
• Improved Discoverability: Users can easily find out which preview features are available to test.

Proposed User Experience (UX)

We suggest an environment variable, tentatively named K6_FEATURES. A user would activate features like this:

# Example: Enable binary provisioning and the new end-of-test summary
export K6_FEATURES=binary-provisioning,end-of-test-summary

# This command would now have access to binary provisioning
k6 cloud script.js

# This command would generate the new summary format (assuming that feature's logic is tied to this flag)
k6 run script.js

Deprecation & Maintenance Plan

To migrate existing experimental features, we propose the following phased approach:

1. Augment: For each existing experimental flag, we will add support for it via the new K6_FEATURES variable. The original, specific flag (e.g., K6_SOME_FEATURE_FLAG) will continue to work.
2. Deprecate: We will mark the old, specific flags as "deprecated" in the documentation and, if possible, log a warning message when they are used.
3. Remove: At the next major version release (e.g., k6 v2.0.0), we will remove the deprecated, specific flags, completing the migration.

Open Questions for Discussion

• Final Naming: What should the final name of the environment variable be?
  • K6_FEATURES?
  • K6_PREVIEW?
  • K6_EXPERIMENTAL_FEATURES?
  • Other suggestions?
• Configuration File Support: Should this also be available as an option in the JSON config file (e.g., options.experimentalFeatures = ["..."]) for better consistency?
• Feature Name Convention: We should standardize on a naming convention. kebab-case (as shown in the example) seems like a sensible default.
• Precedence: If both an old flag and the new K6_PREVIEW flag are set for the same feature, which one takes precedence? (Suggestion: The new K6_PREVIEW flag should have priority).