github.com/kata-containers/runtime@v0.0.0-20210505125100-04f29832a923/virtcontainers/experimental/README.md (about)

     1  # Experimental package description
     2  
     3  * [What are "experimental" features?](#what-are-experimental-features)
     4  * [What's the difference between "WIP" and "experimental"?](#whats-the-difference-between-wip-and-experimental)
     5  * [When should "experimental" features be moved out from "experimental"?](#when-should-experimental-features-be-moved-out-from-experimental)
     6  * [Can "experimental" features fail the CI temporarily?](#can-experimental-features-fail-the-ci-temporarily)
     7  
     8  ## What are "experimental" features?
     9  
    10  "Experimental" features are features living in master branch, 
    11  but Kata community thinks they're not ready for production use.
    12  They are **always disabled** by default in Kata components releases,
    13  and can only be enabled by users when they want to have a try.
    14  
    15  We suggest you **NEVER** enable "experimental" features in production environment,
    16  unless you know what breakage they can bring and have confidence to handle it by yourself.
    17  
    18  Criteria of an experimental feature are:
    19  
    20  * the feature breaks backward compatibility
    21  
    22  compatibility is important to Kata Containers,
    23  We will **NEVER** accept any new features/codes which break the backward compatibility of Kata components,
    24  unless they are so important and there's no way to avoid the breakage.
    25  If we decide to involve such changes, maintainers will help to make the decision that which Kata release
    26  it should land.
    27  
    28  Before it's landed as a formal feature, we allow the codes to be merged first into our master with the tag "experimental",
    29  so it can improve in next few releases to be stable enough.
    30  
    31  * the feature is not stable enough currently
    32  
    33  Some features could be big, it adds/changes lots of codes so may need more tests.
    34  Our CI can help guarantee correctness of the feature, but it may not cover all scenarios.
    35  Before we're confident that the feature is ready for production use,
    36  the feature can be marked as "experimental" first, and users can test it manually in their own environment if interested in it.
    37  
    38  We make no guarantees about experimental features, they can be removed entirely at any point,
    39  or become non-experimental at some release, so relative configuration options can change radically.
    40  
    41  An experimental feature **MUST** have a descriptive name containing only lower-case characters, numbers or `_`, 
    42  e.g. `new_hypervisor_2`, the name **MUST** be unique and will never be re-used in future.
    43  
    44  ## What's the difference between "WIP" and "experimental"?
    45  
    46  "WIP"(work in progress) are usually used to mark the PR as incomplete before the PR can be reviewed and merged,
    47  after the PR finishes its designed purpose(fix bugs, add new features etc) and all CI jobs pass, the codes can be merged into master branch.
    48  After merging, we can still mark this part as "experimental", and leave some space for its evolution in future releases.
    49  
    50  In one word, "experimental" can be unstable currently but it **MUST** be complete and functional, thus different from "WIP".
    51  
    52  ## When should "experimental" features be moved out from "experimental"?
    53  
    54  That depends.
    55  
    56  For the feature that breaks backward compatibility, we usually land it as formal feature in a major version bump(x in x.y.z, e.g. 2.0.0).
    57  But for a new feature who becomes stable and ready, we can release it formally in any minor version bump.
    58  
    59  Check Kata Container [versioning rules](https://github.com/kata-containers/documentation/blob/c556f1853f2e3df69d336de01ad4bb38e64ecc1b/Releases.md#versioning).
    60  
    61  The experimental feature should state clearly in documentation the rationale for it to be experimental, 
    62  and when it is expected to be non-experimental,
    63  so that maintainers can consider to make it formal in right release.
    64  
    65  ## Can "experimental" features fail the CI temporarily?
    66  
    67  No.
    68  
    69  "Experimental" features are part of Kata master codes, it should pass all CI jobs or we can't merge them,
    70  that's different from "WIP", a "WIP" PR can fail the CI temporarily before it can be reviewed and merged.
    71