github/kata-containers
1
0
Fork 1
mirror of https://github.com/kata-containers/kata-containers.git synced 2025-06-30 17:22:33 +00:00
Code Issues Projects Releases Wiki Activity

config: add docs for experimental

Browse Source 
Fixes #1226

Add more docs for experimental features.

Signed-off-by: Wei Zhang <zhangwei555@huawei.com>
This commit is contained in:
Wei Zhang 2019-02-22 14:48:15 +08:00
parent 050f03bb36
commit 111774c859
3 changed files with 64 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
cli/config/configuration-fc.toml.in
View File

@ -294,6 +294,7 @@ disable_guest_seccomp=@DEFDISABLEGUESTSECCOMP@
# Experimental features are features not stable enough for production,
# They may break compatibility, and are prepared for a big version bump.
# Supported experimental features:
# 1. "newstore": new persist storage driver
# 1. "newstore": new persist storage driver which breaks backward compatibility,
# expected to move out of experimental in 2.0.0.
# (default: [])
experimental=@DEFAULTEXPFEATURES@

3
cli/config/configuration-qemu.toml.in
View File

@ -341,6 +341,7 @@ disable_guest_seccomp=@DEFDISABLEGUESTSECCOMP@
# Experimental features are features not stable enough for production,
# They may break compatibility, and are prepared for a big version bump.
# Supported experimental features:
# 1. "newstore": new persist storage driver
# 1. "newstore": new persist storage driver which breaks backward compatibility,
# expected to move out of experimental in 2.0.0.
# (default: [])
experimental=@DEFAULTEXPFEATURES@

60
virtcontainers/experimental/README.md Normal file
View File

@ -0,0 +1,60 @@
# Experimental package description
## 1. What are "experimental" features?
"Experimental" features are features living in master branch,
but Kata community thinks they're not ready for production use.
They are **always disabled** by default in Kata components releases,
and can only be enabled by users when they want to have a try.
We suggest you **NEVER** enable "experimental" features in production environment,
unless you know what breakage they can bring and have confidence to handle it by youself.
Criteria of an experimental feature are:
* the feature breaks backward compatibility
compatibility is important to Kata Containers,
We will **NEVER** accept any new features/codes which break the backward compatibility of Kata components,
unless they are so important and there's no way to avoid the breakage.
If we decide to involve such changes, maintainers will help to make the decision that which Kata release
it should land.
Before it's landed as a formal feature, we allow the codes to be merged first into our master with the tag "experimental",
so it can improve in next few releases to be stable enough.
* the feature is not stable enough currently
Some features could be big, it adds/changes lots of codes so may need more tests.
Our CI can help guarantee correctness of the feature, but it may not cover all scenarios.
Before we're confident that the feature is ready for production use,
the feature can be marked as "experimental" first, and users can test it manually in their own environment if intested in it.
## 2. What's the difference between "WIP" and "experimental"?
"WIP"(work in progress) are usually used to mark the PR as incomplete before the PR can be reviewed and merged,
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.
After merging, we can still mark this part as "experimental", and leave some space for its evolvement in next several releases.
In one word, "experimental" can be unstable currently but it **MUST** be complete and functional, thus different from "WIP".
## 3. When should "experimental" features be moved out from "experimental"?
That depends.
For the feature who 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).
But for a new feature who becomes stable and ready, we can release it formally in any minor version bump.
Check Kata Container [versioning rules](https://github.com/kata-containers/documentation/blob/c556f1853f2e3df69d336de01ad4bb38e64ecc1b/Releases.md#versioning).
The experimental feature should state clearly in documentation the rationale for it to be experimental,
and when it is expected to be non-experimental,
so that maintainers can consider to make it formal in right release.
## 4. Can "experimental" features fail the CI temporarily?
No.
"Experimental" features are part of Kata master codes, it should pass all CI jobs or we can't merge them,
that's different from "WIP", a "WIP" PR can fail the CI temporarily before it can be reviewed and merged.