mirror of https://github.com/helm/helm
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
89 lines
3.5 KiB
89 lines
3.5 KiB
# 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
|
|
|
|
```bash
|
|
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](https://github.com/helm/community/blob/main/hips/hip-0004.md).
|
|
|
|
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
|