Skip to content

Commit b2d5063

Browse files
Copilotyxxhero
Copilot
and
yxxhero
authored
Add comprehensive GitHub Copilot instructions for helm-diff development (#838)
* Initial plan * Add comprehensive GitHub Copilot instructions with validated commands and timing Co-authored-by: yxxhero <[email protected]> --------- Co-authored-by: copilot-swe-agent[bot] <[email protected]> Co-authored-by: yxxhero <[email protected]>
1 parent 4bde4c9 commit b2d5063

File tree

1 file changed

+137
-0
lines changed

1 file changed

+137
-0
lines changed

‎.github/copilot-instructions.md

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
# Helm Diff Plugin
2+
3+
Helm Diff is a Go-based Helm plugin that provides diff functionality for comparing Helm charts and releases. It shows what changes would occur during helm upgrade, rollback, or between different releases/revisions.
4+
5+
Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.
6+
7+
## Working Effectively
8+
9+
**Prerequisites:**
10+
- Go >= 1.21 (currently uses Go 1.24.5)
11+
- Helm v3 (tested with v3.17.4 and v3.18.6)
12+
- Make sure `/home/runner/go/bin` is in your PATH for staticcheck: `export PATH=$PATH:/home/runner/go/bin`
13+
14+
**Bootstrap and Build Process:**
15+
- ALWAYS run: `make bootstrap` first - downloads dependencies and installs staticcheck. Takes <1 second (if already done) or ~50 seconds (first time).
16+
- Build the plugin: `make build` - includes linting and compiles the binary. Takes ~9 seconds after bootstrap.
17+
- NEVER CANCEL builds. Set timeout to 3+ minutes for bootstrap, 2+ minutes for build operations.
18+
19+
**Testing:**
20+
- Run unit tests: `make test` - includes coverage analysis. Takes ~12 seconds. NEVER CANCEL - set timeout to 3+ minutes.
21+
- Tests include comprehensive coverage (38.7% overall) and use a fake helm binary for isolation.
22+
- Test coverage is generated in `cover.out` with detailed function-level coverage reports.
23+
24+
**Linting and Code Quality:**
25+
- Local linting: `make lint` - runs gofmt, go vet, and staticcheck verification. Takes ~2 seconds.
26+
- Code formatting: `make format` - applies gofmt formatting automatically. Takes <1 second.
27+
- Full golangci-lint runs only in CI via GitHub Actions, not available locally.
28+
- ALWAYS run `make format` and `make lint` before committing changes.
29+
30+
**Plugin Installation:**
31+
- Install as Helm plugin: `make install` or `make install/helm3` - builds and installs to Helm plugins directory. Takes ~3 seconds.
32+
- The plugin installs via `install-binary.sh` script which handles cross-platform binary installation.
33+
34+
## Validation Scenarios
35+
36+
**ALWAYS test your changes with these scenarios:**
37+
38+
1. **Basic Plugin Functionality:**
39+
```bash
40+
# Test the binary directly
41+
./bin/diff version
42+
./bin/diff --help
43+
./bin/diff upgrade --help
44+
```
45+
46+
2. **Real Chart Diffing:**
47+
```bash
48+
# Create a test chart and diff it
49+
cd /tmp && helm create test-chart
50+
cd /path/to/helm-diff
51+
HELM_NAMESPACE=default HELM_BIN=helm ./bin/diff upgrade --install --dry-run test-release /tmp/test-chart
52+
```
53+
54+
3. **Plugin Installation Verification:**
55+
```bash
56+
# Test plugin installation
57+
export HELM_DATA_HOME=/tmp/helm-test
58+
make install
59+
/tmp/helm-test/plugins/helm-diff/bin/diff version
60+
```
61+
62+
## Build Times and Timeouts
63+
64+
**CRITICAL: NEVER CANCEL long-running commands. Use these timeout values:**
65+
66+
- `make bootstrap`: <1 second (if already done) or ~50 seconds (first time) (set timeout: 5+ minutes)
67+
- `make build`: ~9 seconds after bootstrap (set timeout: 3+ minutes)
68+
- `make test`: ~12 seconds (set timeout: 3+ minutes)
69+
- `make lint`: ~2 seconds (set timeout: 1 minute)
70+
- `make format`: <1 second (set timeout: 1 minute)
71+
- `make install`: ~3 seconds (set timeout: 2 minutes)
72+
73+
## Common Tasks
74+
75+
**Repository Structure:**
76+
- `main.go` - Entry point that delegates to cmd package
77+
- `cmd/` - Command-line interface implementation (upgrade, release, revision, rollback, version)
78+
- `diff/` - Core diffing logic and output formatting
79+
- `manifest/` - Kubernetes manifest parsing and handling
80+
- `scripts/` - Build and verification scripts (gofmt, govet, staticcheck)
81+
- `testdata/`, `*/testdata/` - Test fixtures and mock data
82+
- `plugin.yaml` - Helm plugin configuration
83+
- `install-binary.sh` - Cross-platform installation script
84+
- `Makefile` - Build system with all common targets
85+
86+
**Key Files to Check After Changes:**
87+
- Always run tests after modifying `cmd/` or `diff/` packages
88+
- Check `plugin.yaml` version if making release changes
89+
- Verify `Makefile` targets if changing build process
90+
- Review `install-binary.sh` if modifying installation process
91+
92+
**Environment Variables for Testing:**
93+
- `HELM_NAMESPACE` - Kubernetes namespace for operations
94+
- `HELM_BIN` - Path to helm binary (for direct testing)
95+
- `HELM_DIFF_USE_UPGRADE_DRY_RUN` - Use helm upgrade --dry-run instead of template
96+
- `HELM_DIFF_THREE_WAY_MERGE` - Enable three-way merge diffing
97+
- `HELM_DIFF_NORMALIZE_MANIFESTS` - Normalize YAML before diffing
98+
- `HELM_DIFF_OUTPUT_CONTEXT` - Configure output context lines
99+
100+
**CI/CD Information:**
101+
- GitHub Actions runs on push/PR to master branch
102+
- Tests run on Ubuntu, macOS, Windows with multiple Helm versions
103+
- Integration tests use Kind (Kubernetes in Docker)
104+
- Linting uses golangci-lint via GitHub Actions (not available locally)
105+
- Cross-platform plugin installation is tested via Docker
106+
107+
**Direct Binary Usage (for development):**
108+
```bash
109+
# Build and test directly without Helm plugin installation
110+
go build -o bin/diff -ldflags="-X github.com/databus23/helm-diff/v3/cmd.Version=dev"
111+
HELM_NAMESPACE=default HELM_BIN=helm ./bin/diff upgrade --install --dry-run my-release ./chart-path
112+
```
113+
114+
**Common Commands Reference:**
115+
```bash
116+
# Full development cycle
117+
make bootstrap # Install dependencies (once)
118+
make build # Build with linting
119+
make test # Run all tests
120+
make format # Format code
121+
make install # Install as Helm plugin
122+
123+
# Validation
124+
./bin/diff version # Check version
125+
./bin/diff upgrade --help # Check help
126+
make test # Run test suite
127+
```
128+
129+
## Important Notes
130+
131+
- The plugin supports Helm v3 only (v2 support was removed)
132+
- Uses Go modules for dependency management
133+
- Cross-platform support: Linux, macOS, Windows, FreeBSD
134+
- Multiple output formats: diff, simple, template, dyff
135+
- Supports both client-side and server-side dry-run modes
136+
- Includes three-way merge capabilities for advanced diffing
137+
- Plugin binary is named `diff` and installed as `helm diff` command

0 commit comments

Comments
 (0)