H4HIP: Adding a HIP on charts v3

hips/README.md

@@ -28,3 +28,4 @@ restricted markdown format and can be found in the
 - [hip-0017: Helm OCI MediaType Registration](hip-0017.md)
 - [hip-0018: Include repository URL and tarball digest in chart's release metadata](hip-0018.md)
 - [hip-0019: New annotations for displaying hook output](hip-0019.md)
+- [hip-0020: H4HIP: Charts v3 Enablement](hip-0020.md)

hips/hip-0020.md

@@ -0,0 +1,133 @@
+---
+hip: "0020"
+title: "H4HIP: Charts v3 Enablement"
+authors: [ "Matt Farina <[email protected]>" ]
+created: "2025-01-09"
+type: "feature"
+status: "accepted"
+---
+
+## Abstract
+
+This HIP proposes the creation of charts v3, updating Helm to handle charts v2 and v3, and a
+timeline for the general availability of charts v3 that can happen after the release of Helm v4.0.0.
+
+## Motivation
+
+Many of the proposed changes for Helm v4 affect charts. Layering these onto existing charts will
+sometimes cause chart installation and upgrade to happen differently in Helm v3 and Helm v4, as
+both will need to live side by side for a time. It also means that testing of charts for v3 can produce
+a different result when installed with Helm v4.
+
+In addition to the affects of the changes, Helm v4 development has a fixed timeline and making
+changes to Helm in addition to reworking charts is not likely to fit within that fixed window. Enabling
+the development of charts v3 to happen as an experiment that becomes generally available after
+the release of Helm v4 provides more time to continue the work and get feedback.
+
+The goal is to provide adequate time to work on chart changes while doing it in a way that enables
+trust in existing charts to run as they were tested.
+
+## Rationale
+
+Charts v2 were created for Helm v3 and introduced minor changes. The code that handles the chart
+versions is the same with some checking to handle the differences. This handling ended up having
+numerous bugs that had to be worked out in patch releases.
+
+The chart changes being proposed for Helm v4 are more significant. Mixing those in alongside the
+current chart version handling will have trouble limiting bugs will enabling the changes and keeping
+existing charts functioning properly.
+
+The design specified here is meant to enable the current charts to work as expected while providing
+space for more radical changes.
+
+## Specification
+
+Describe the syntax and semantics of any new feature.
+
+Helm has numerous packages that do various things, from working with charts to storing release
+information. These packages all expect there to be one version of a particular thing. To support
+multiple versions of charts, the `chart`, `chartutil`, `engine`, and `release` packages will be made
+multi-version. (e.g., engine will have a v1 and v2 versions). In addition to enabling a new version of
+charts, this will enable the gotpl engine to evolve as needed to support the new version of charts. 
+The `chartutil` may be combined with the `chart` package and the `releaseutil` package may be
+combined with the `release` package for simplification of the package structure.
+
+The versioning of the packages will follow the same structure that Kubernetes does with its APIs.
+This means a thing will have a directory and within it will be sub-directories for the versions. The
+version specific implementation will be in the version specific sub-directory. For example,
+
+```
+chart
+├── v2
+└── v3
+```
+
+The version will not use a separate Git repository or Go modules. The reason for this is the added
+complexity of managing the repositories and modules is added work to manage changes which will
+slow down velocity, will make releases more complex, and make the Helm SDK more complicated
+to work with.
+
+The existing versions of these packages will be externally facing while the new versions will be
+developed in `internal` as experiments until they are complete enough for release. When ready for
+release, these packages will be moved to the public locations.
+
+To illustrate this, while in development the `chart` package will have the following structure:
+
+```
+internal/chart
+└── v3
+pkg/chart
+└── v2
+```
+
+Once the new chart packages have (a) a stable API and (b) are feature complete the structure will
+be merged to look like:
+
+```
+pkg/chart
+├── v2
+└── v3
+```
+
+While in development, as an experiment, the `pkg/gates` package will be used to create an opt-in
+environment variable to enable a new chart version. This is how the OCI experimental feature was
+handled.
+
+## Backwards compatibility
+
+This development and process is designed with backwards compatibility in mind. The package
+locations will change, which is ok in a major version of Helm. The existing charts will be preserved
+so that their installation process continues to work as expected from Helm v3. New features and
+changes to charts can be added in without impacting existing charts.
+
+While the new chart version is being developed and is going through breaking changes, the chart
+will be an opt-in feature which will enable us to warn users about the state of it.
+
+## Security implications
+
+N/A
+
+## How to teach this
+
+There are a few ways to teach this:
+
+1. **Documentation**: The chart documentation will be updated to teach both versions of charts.
+2. **Helm Create**: Helm create will be updated to use the new chart version and provide an example.
+3. **Blog and Webinars**: The marketing options open to Helm will be used to share details and teach about the new chart version.
+
+## Reference implementation
+
+N/A
+
+## Rejected ideas
+
+An option to detect the chart version within existing code was seen as an option. This is how
+charts `apiVersion` is handled for `v1` and `v2`. This is problematic as large changes in charts
+will be difficult to work on and test to ensure nothing breaks across version.
+
+## Open issues
+
+N/A
+## References
+
+N/A