BEP 10: Policy for Experimental Features
| BEP 10 | Policy for Experimental Features |
|---|---|
| Authors | Bryan Van de Ven |
| Status | Implemented |
| Discussion | https://github.com/bokeh/bokeh/discussions/12421 |
This document describes required policies for adding experimental features.
In some cases it may be desirable to add new features before they are fully developed. This could be because the feature is deemed to be extremely important, enough that putting it in the hands of users is an overriding priority. Or because fully developing the feature requires obtaining feedback from actual usage to drive future refinements.
At the same time, it is important to communicate this experimental status to users as effectively and unequivocally as possible. This is primarily in order that users may make informed decisions whether to use an experimental feature or not. However, the requirements in laid out in this BEP can also serve to head off unnecessary support questions surrounding changes to experimental features.
The definition of "experimental feature" is intended to cover any new features for which future changes are considered likely. If there is any motivation to include any notice in a docstring, etc. about the likelihood that a given feature may change in the future, then the requirements of this BEP shall apply.
Bokeh model properties may be marked experimental. At the time of writing, the Plot.extra_x_scales property is a current example:
extra_x_scales = Dict(String, Instance(Scale), help="""
Additional named scales to make available for mapping x-coordinates.
This is useful for adding additional axes.
.. note:: This feature is experimental and may change in the short term.
""")This property could change in several ways:
- The type (range of acceptable values) may change
- The default value may change
- The behavior caused or controlled by the property value may change
- The property may be renamed or removed altogether
Bokeh models themselves may be marked experimental for similar reasons.
Bokeh classes and functions may be marked experimental:
- The call signature or default values may change in incompatible ways
- The behavior caused or controlled by the function or class may change
- The function or class may be renamed or removed altogether
This section stipulates requirements for documentation, warning, and testing that must be met for the inclusion of an experimental feature.
Docstrings or property helpstrings related to experimental features shall include the following boilerplate admonition:
.. warning::
{feature name} is currently experimental. It is subject to change or removal in future releases.A BokehUserWarning subclass will be added for raising experimental feature warnings:
class BokehExperimentalWarning(BokehUserWarning):
''' Warn that a specific feature is currently experimental. '''This warning shall be issued whenever an experimental feature is explicitly invoked by a user (e.g. by setting a particular property, or by calling a specific API function):
warnings.warn(message, BokehExperimentalWarning, stacklevel=stacklevel)where the text of message is the same as the documentation admonition.
A unit test test_experimental_{feature name} shall be added to an appropriate test module. This test will check for the presence of the warning admonition in relevant documentation, and also check that a BokehExperimentalWarning is issued when the feature is activated.
All three of the requirements must remain in place until it is decided that a feature is no longer experimental, and unlikely to change. At that time, the documentation, warning, and test shall all be removed in the next subsequent release.
| Date | Change |
|---|---|
| 2023-01-05 | Implemented |