Skip to content

Add feature flagging system#1783

Open
HT154 wants to merge 1 commit into
apple:mainfrom
HT154:feature-flags
Open

Add feature flagging system#1783
HT154 wants to merge 1 commit into
apple:mainfrom
HT154:feature-flags

Conversation

@HT154

@HT154 HT154 commented Jul 17, 2026

Copy link
Copy Markdown
Contributor

Adds:

  • New CLI flag --feature=<name>=[true|false]
  • Pkl API
    • Property pkl.EvaluatorSettings#featureFlags: Mapping<KnownFeatureFlags | String, Boolean>
    • Typealias pkl.EvaluatorSettings#FeatureFlags = nothing (no feature flags yet, but this will be a string literal union)
  • Java API
    • org.pkl.core.FeatureFlags - enum to document feature flags and their default values.
    • org.pkl.core.evaluatorSettings.PklEvaluatorSettings.featureFlags
    • org.pkl.core.Analyzer now requires constructor argument Map<FeatureFlag, Boolean> featureFlags
    • org.pkl.core.EvaluatorBuilder
      • addFeatureFlag, addFeatureFlags, setFeatureFlags, getFeatureFlags
      • applyFromProject(Project, Logger) (for capturing string->FeatureFlag conversion warnings)
        • The overload without the Logger argument now passes Loggers.noop() to this API
    • org.pkl.config.java.ConfigEvaluatorBuilder.applyFromProject(Project, Logger) (for capturing string->FeatureFlag conversion warnings)
      • The overload without the Logger argument now passes Loggers.noop() to this API
    • org.pkl.core.Logger (changes to assist with warnings not from Pkl code)
      • trace(String message, String frameUri) (now called by trace(String, StackFrame))
      • warn(String message, String frameUri) (now called by warn(String, StackFrame))
  • Gradle tasks now accept featureFlags (as a MapProperty<String, Boolean>)
  • Message passing API CreateEvaluatorRequest now accepts a map property featureFlags, which is a map of string to boolean values.

Feature flag lifecycle:

  1. Feature flags are added by adding a case to org.pkl.core.FeatureFlags.
  2. Flags may change default values as the language evolves.
  3. Prior to removal, enum cases should be marked @Deprecated for at least one release to provide Java API users an opportunity to discontinue usage.
  4. Finally, a flag is retired by removing its enum case and any code accessing its value.

Notably, because Pkl's stdlib is statically initialized with a separate VmContext, it can set its own feature flags independently of each user-initiated evaluation!

@HT154
HT154 force-pushed the feature-flags branch 6 times, most recently from f7f0441 to dd067c6 Compare July 17, 2026 18:39
Comment on lines +129 to +142
/// Register external module readers.
///
/// Added in Pkl 0.27.0.
externalModuleReaders: Mapping<String, ExternalReader>?

/// Register external resource readers.
///
/// Added in Pkl 0.27.0.
externalResourceReaders: Mapping<String, ExternalReader>?

/// Dictates the rendering of calls to the trace() method within Pkl.
///
/// Added in Pkl 0.30.0.
traceMode: ("compact" | "pretty")?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Whoops, we've missed updating this for a bit!

@HT154
HT154 marked this pull request as ready for review July 17, 2026 19:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant