helm/AGENTS.md

AGENTS.md

Overview

Helm is a package manager for Kubernetes written in Go. It enables users to define, install, and upgrade complex Kubernetes applications using charts. This document provides an overview of the codebase structure, development guidelines, and key patterns for contributors.

The codebase supports both an SDK for advanced users, and a CLI for direct end user usage.

The project currently supports Helm v3 and Helm v4 versions, based on the dev-v3 and main branches respectively.

Build and test

make build              # Build binary
make test               # Run all tests (style + unit)
make test-unit          # Unit tests only
make test-coverage      # With coverage
make test-style         # Linting (wraps golangci-lint)
go test -run TestName   # Specific test

Code structure

Major packages:

• cmd/helm/ - CLI entry point, wires CLI flags to pkg/cmd/ commands
• pkg/ - Public API
  • action/ - Core operations (install, upgrade, rollback)
  • cmd/ - Cobra command implementations bridging CLI flags to pkg/action/
  • chart/v2/ - Stable chart format
  • engine/ - Template rendering (Go templates + Sprig)
  • kube/ - Kubernetes client abstraction layer
  • registry/ - OCI support
  • release/ - Release types and interfaces (v1/, common/)
  • repo/ - Chart repository indexing and interaction
  • storage/ - Release backends (Secrets/ConfigMaps/SQL)
• internal/ - Private implementations
  • chart/v3/ - Next-gen chart format
  • release/v2/ - Release package for chart v3 support

Development

Compatibility

Changes are required to maintain backward compatibility as described in HIP-0004: Document backwards-compatibility rules.

Typically this means that:

• the signatures of public APIs, i.e., those in the pkg/ directory should not change
• CLI commands and parameters should not be removed or changed in a way that would break existing scripts or workflows
• functional behaviour (as implied or documented) must not be modified in a way that would break existing users' expectations

An exception to the above is where incompatible changes are needed to fix a security vulnerability, where minimal breaking changes may be made to address the issue.

Code standards

• Use table-driven tests with testify
• Golden files in testdata/ for complex output
• Mock Kubernetes clients for action tests
• All commits must include DCO sign-off: git commit -s

Branching

Standard workflow is for PR development changes to the main branch. Minor release branches are cut from main, then maintained for critical fixes via patch releases. Bug and security fixes are also backported to dev-v3 where applicable.

Development branches:

• main - Helm v4
• dev-v3 - Helm v3 (backport security and bugfixes from main)

Release branches:

• release-v3.X - Release branches for v3.X versions
• release-v4.X - Release branches for v4.X versions

Major dependencies

• k8s.io/client-go - Kubernetes interaction
• github.com/spf13/cobra - CLI framework
• github.com/Masterminds/sprig - Template functions

Key patterns

• Actions: High-level operations live in pkg/action/, typically using a shared Configuration
• Chart versions: Charts v2 (stable) in pkg/chart/v2, v3 (under development) in internal/chart/v3
• Plugins and extensibility: Enabling additional functionality via plugins and extension points, such as custom template functions or storage backends is preferred over incorporating into Helm's codebase