Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add draft/experimental feature class #6066

Closed
garlick opened this issue Jun 29, 2024 · 0 comments
Closed

add draft/experimental feature class #6066

garlick opened this issue Jun 29, 2024 · 0 comments

Comments

@garlick
Copy link
Member

garlick commented Jun 29, 2024

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.

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.

Fixes flux-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.

Fixes flux-framework#6066
@mergify mergify bot closed this as completed in 52f18aa Jul 2, 2024
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

No branches or pull requests

1 participant