You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Problem: some new features may be just intended for testing by early adopters and subject to abrubt removal or change, yet we have no formal way to tag such features.
@grondo brought up the idea of designating housekeeping (#5818) as experimental and this reminded me of zeromq's DRAFT API designation.
Zeromq man pages for draft features contain warnings like
NOTE: in DRAFT state, not yet available in stable releases.
Zeromq also offers the ability to compile out DRAFT interfaces, and I note tha SUSE distributes both draft and non draft RPMs for zermoq. Draft vs non-draft builds might be going too far for flux-core at this stage but it seems like it might be useful to at least have a formal designation in flux for such features to set expectations in a uniform way and not have to re-explain what "experimental" means to us for each of them. Maybe for the man pages for such features we could include a generic section that says something like:
DRAFT
DRAFT features are made available for evaluation only and may change or be removed without notice. If you find this feature useful or have critical feedback please open an issue or discussion at this project's github site (link).
Note that RFC 1 does have a bit to say about experimental interfaces. Of course we can change that to fit our needs as it was inherited from zeromq.
The text was updated successfully, but these errors were encountered:
garlick
added a commit
to garlick/flux-core
that referenced
this issue
Jul 1, 2024
Problem: the text to explain expectations for experimental features
must be repeated in documentation for each one which is extra work
for both the author and the reader.
Add common/experimental.rst which can be included from man pages
that discuss experimental features. Like common/resource.rst, the
idea is to make it a standalone section which can then be referenced
from the feature documentation.
This should improve consistency and make it easier to document these
features and interfaces.
Fixesflux-framework#6066
garlick
added a commit
to garlick/flux-core
that referenced
this issue
Jul 1, 2024
Problem: the text to explain expectations for experimental features
must be repeated in documentation for each one which is extra work
for both the author and the reader.
Add common/experimental.rst which can be included from man pages
that discuss experimental features. Like common/resource.rst, the
idea is to make it a standalone section which can then be referenced
from the feature documentation.
This should improve consistency and make it easier to document these
features and interfaces.
Fixesflux-framework#6066
Problem: some new features may be just intended for testing by early adopters and subject to abrubt removal or change, yet we have no formal way to tag such features.
@grondo brought up the idea of designating housekeeping (#5818) as experimental and this reminded me of zeromq's DRAFT API designation.
Zeromq man pages for draft features contain warnings like
Zeromq also offers the ability to compile out DRAFT interfaces, and I note tha SUSE distributes both draft and non draft RPMs for zermoq. Draft vs non-draft builds might be going too far for flux-core at this stage but it seems like it might be useful to at least have a formal designation in flux for such features to set expectations in a uniform way and not have to re-explain what "experimental" means to us for each of them. Maybe for the man pages for such features we could include a generic section that says something like:
Note that RFC 1 does have a bit to say about experimental interfaces. Of course we can change that to fit our needs as it was inherited from zeromq.
The text was updated successfully, but these errors were encountered: