docs(chart): surface OCI annotations in Chart.yaml

Signed-off-by: abhay1999 <abhaychaurasiya19@gmail.com>

internal/chart/v3/util/create.go

@@ -102,6 +102,18 @@ version: 0.1.0
 # follow Semantic Versioning. They should reflect the version the application is using.
 # It is recommended to use it with quotes.
 appVersion: "1.16.0"
+
+# Additional annotations to add to the chart metadata.
+# They are made available to other applications and copied to the
+# OCI manifest when the chart is pushed to an OCI registry.
+annotations:
+  # Artifact Hub annotations:
+  # artifacthub.io/changes: |
+  #   - kind: added
+  #     description: Initial release
+  # OCI annotations:
+  # org.opencontainers.image.source: "https://github.com/example/repo"
+  # org.opencontainers.image.revision: "0123456789abcdef"
 `
 
 const defaultValues = `# Default values for %s.

pkg/chart/v2/metadata.go

@@ -74,6 +74,9 @@ type Metadata struct {
 	Deprecated bool `json:"deprecated,omitempty"`
 	// Annotations are additional mappings uninterpreted by Helm,
 	// made available for inspection by other applications.
+	// When charts are pushed to OCI registries, Helm copies chart
+	// annotations into the OCI manifest annotations, except for
+	// immutable OCI keys generated by Helm such as title and version.
 	Annotations map[string]string `json:"annotations,omitempty"`
 	// KubeVersion is a SemVer constraint specifying the version of Kubernetes required.
 	KubeVersion string `json:"kubeVersion,omitempty"`

pkg/chart/v2/util/create.go

@@ -102,6 +102,18 @@ version: 0.1.0
 # follow Semantic Versioning. They should reflect the version the application is using.
 # It is recommended to use it with quotes.
 appVersion: "1.16.0"
+
+# Additional annotations to add to the chart metadata.
+# They are made available to other applications and copied to the
+# OCI manifest when the chart is pushed to an OCI registry.
+annotations:
+  # Artifact Hub annotations:
+  # artifacthub.io/changes: |
+  #   - kind: added
+  #     description: Initial release
+  # OCI annotations:
+  # org.opencontainers.image.source: "https://github.com/example/repo"
+  # org.opencontainers.image.revision: "0123456789abcdef"
 `
 
 const defaultValues = `# Default values for %s.

pkg/chart/v2/util/create_test.go

@@ -20,6 +20,7 @@ import (
 	"bytes"
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 
 	chart "helm.sh/helm/v4/pkg/chart/v2"
@@ -45,6 +46,22 @@ func TestCreate(t *testing.T) {
 		t.Errorf("Expected name to be 'foo', got %q", mychart.Name())
 	}
 
+	chartFileData, err := os.ReadFile(filepath.Join(dir, ChartfileName))
+	if err != nil {
+		t.Fatalf("Failed to read generated %s: %s", ChartfileName, err)
+	}
+
+	chartFile := string(chartFileData)
+	for _, expected := range []string{
+		"annotations:",
+		"org.opencontainers.image.revision:",
+		"OCI manifest when the chart is pushed to an OCI registry.",
+	} {
+		if !strings.Contains(chartFile, expected) {
+			t.Errorf("Expected generated %s to contain %q", ChartfileName, expected)
+		}
+	}
+
 	for _, f := range []string{
 		ChartfileName,
 		DeploymentName,