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:
@unstableattribute 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
foowill 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-unstableflag. 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.
Add a check against
compilerWarning()to generate the message. This strategy is best for features that can’t be represented by a symbol with the
All unstable features should have a test added 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.