From ae7e3046b719df1b17c7a0f60110f22480b47d06 Mon Sep 17 00:00:00 2001 From: Yusuke Kuoka Date: Thu, 9 May 2024 11:18:29 +0900 Subject: [PATCH] v1: Document experimental features (#1512) See the updated v1 proposal for why we need it now. Signed-off-by: Yusuke Kuoka --- docs/experimental-features.md | 7 +++++++ docs/proposals/towards-1.0.md | 12 ++++++++++++ mkdocs.yml | 1 + 3 files changed, 20 insertions(+) create mode 100644 docs/experimental-features.md diff --git a/docs/experimental-features.md b/docs/experimental-features.md new file mode 100644 index 00000000..f081173b --- /dev/null +++ b/docs/experimental-features.md @@ -0,0 +1,7 @@ +# Experimental Features + +This document describes the experimental features that are available in Helmfile v1. + +Any experimental feature may be removed or changed in a future release without notice. + +- HCL helmfile-values-file support (PR #1423) diff --git a/docs/proposals/towards-1.0.md b/docs/proposals/towards-1.0.md index 70506fb5..29e3b6bd 100644 --- a/docs/proposals/towards-1.0.md +++ b/docs/proposals/towards-1.0.md @@ -11,6 +11,7 @@ Note that every breaking change should have an easy alternative way to achieve t 3. [Remove the `--args` flag from the `helmfile` command](#remove-the---args-flag-from-the-helmfile-command) 4. [Remove `HELMFILE_SKIP_INSECURE_TEMPLATE_FUNCTIONS` in favor of `HELMFILE_DISABLE_INSECURE_FEATURES`](#remove-helmfile_skip_insecure_template_functions-in-favor-of-helmfile_disable_insecure_features) 5. [The long deprecated `charts.yaml` has been finally removed](#the-long-deprecated-chartsyaml-has-been-finally-removed) +6. [List experimental features](#list-experimental-features) ### Forbid the use of `environments` and `releases` within a single helmfile.yaml.gotmpl part @@ -82,6 +83,17 @@ Note that every breaking change should have an easy alternative way to achieve t Helmfile used to load `helmfile.yaml` or `charts.yaml` when you omitted the `-f` flag. `charts.yaml` has been deprecated for a long time but never been removed. We take v1 as a chance to finally remove it. +### List experimental features + +We have some experimental features that are not stable yet. We should list them in a list and mark them as experimental. + +In Helmfile v1.x, all features should be backward-compatible within v1.x as we follow semver. We can't fix features in a backward incompatible way by default. To do so, we need a list of experimental features and say "anything in the experimentals can be modified backward-incompatible ways", and include features that are consireded experimental into the list beforehand. + +Why now? + +In Helmfile v0.x, all features considered experimental as we follow semver. However, we "ended up" preserving backward-compatibility within v0 and between v0 and v1 "by chance". This doesn't mean anything +introduced in v0 is stable. For example, we might have some features implemented in a very later stage of v0 that are not stable yet. We should mark them as experimental, or we can't fix them in a backward-incompatible way in v1.x. That's why we need to list experimental features now. + ## After 1.0 We won't add any backward-incompatible changes while in 1.x, as long as it's inevitable to fix unseen important bug(s). diff --git a/mkdocs.yml b/mkdocs.yml index de411ec5..2378c9db 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -25,6 +25,7 @@ nav: - Advanced Features: advanced-features.md - Secrets: remote-secrets.md - Shared Configuration Across Teams: shared-configuration-across-teams.md + - Experimental Features: experimental-features.md - About: - Users: users.md - License: license.md