Unstable Features

When it is known that a feature is likely to require discussion or changes but it is uncertain how the interface would be changed, the feature can be designated “unstable”. When compiling Chapel code with the flag --warn-unstable, unstable features will generate a warning when used.

Unstable features have no explicit timeline for stabilization.

There are two ways to mark a feature as unstable:

  1. Use the @unstable attribute and optionally a string literal message. This strategy is best for symbols, as it can be applied to any symbol in a uniform way. Look in the test/unstable and test/unstable-keyword directories for many examples.

    When a string literal is not provided, the default message is foo is unstable, where foo will be replaced with the name of the symbol in question. This message will be used for the unstable symbol’s documentation and for the message generated by the compiler with the --warn-unstable flag. If there is a documentation comment applied to the symbol, that comment will take precedence when producing documentation. When the compiler produces a warning, it will be filtered to remove any inline markup.

    This means that if your unstable message points to a more stable feature like this: foo is unstable - please use :proc:`bar`, then in the generated documentation “bar” will link to the documentation for the “bar” procedure and when producing the compiler warning the “:proc:” syntax and backticks will be filtered out.

  2. Add a check against chpl__warnUnstable and use compilerWarning() to generate the message. This strategy is best for features that can’t be represented by a symbol with the @unstable attribute.

All unstable features should have a test added to test/unstable to:

  • confirm the unstable warning works as intended

  • remind us to take the necessary actions to stabilize the unstable feature, whether that be design discussions or ultimately removing the feature.