Development Guide

1. Building the Project

./mvnw clean install

2. Module Dependencies

jhelm (parent)
├── jhelm-gotemplate-helm (Helm template functions; depends on: gotmpl4j)
├── jhelm-core (depends on: jhelm-gotemplate-helm, gotmpl4j)
├── jhelm-kube (depends on: jhelm-core)
├── jhelm-rest (depends on: jhelm-core, jhelm-kube)
├── jhelm-plugin (Maven packaging plugin)
└── jhelm-cli (depends on: jhelm-core, jhelm-kube)

The Go template + Sprig engine is the external gotmpl4j library (Maven Central); jhelm provides only the Helm-specific function layer.

3. Testing

  • Unit Tests: Each module has comprehensive unit tests.

  • Integration Tests: KpsComparisonTest.java compares output with native Helm.

  • Template Tests: GoTemplateStandardTest.java, TemplateTest.java.

3.1. Testing Guidelines

Always run tests after making code changes to ensure they don’t break existing functionality. 
# Run all tests
./mvnw test

# Run tests for specific module
./mvnw test -pl jhelm-core

# Run specific test class
./mvnw test -Dtest=KpsComparisonTest -pl jhelm-core

# Run specific test method
./mvnw test -Dtest=KpsComparisonTest#testSimpleRendering -pl jhelm-core

Before committing changes:

  1. Run relevant tests to verify your changes work

  2. Check that existing tests still pass

  3. Add new tests for new functionality

  4. Fix any test failures before pushing

4. Versioning and Branches

jhelm keeps its own MAJOR.MINOR.PATCH version; it does not copy the Spring Boot version. Branches are named after the Spring Boot line they build on.

  • main builds on the newest supported Spring Boot line and takes all new features. A feature release is a new jhelm minor, and several minors can share one Spring Boot line.

  • Moving main to a new Spring Boot minor always starts a new jhelm minor. First cut the outgoing line to a branch named <boot-major>.<boot-minor> (for example 4.0) from the pre-bump head.

  • A maintenance branch gets bug fixes and Spring Boot patch bumps only, released as jhelm patch versions. No new features — the next minor numbers belong to main.

  • Every Spring Boot line change adds a row to the compatibility table in README.adoc and docs/modules/ROOT/pages/index.adoc.

5. Debugging Tips

  • Enable detailed logging with @Slf4j annotations.

  • Check test_output.txt and jhelm-core/test_output.txt for test results.

  • Use GoTemplateStandardTest to verify template behavior.

  • Compare output with Helm using dry-run tests in KpsComparisonTest.

6. Common Operations

6.1. Adding a new template function

Helm-specific functions live in this repository, in jhelm-gotemplate-helm. Sprig and Go builtins live in the external gotmpl4j project — add or fix those there.

To add a Helm function:

  1. Choose the category package: helm/conversion/, helm/template/, helm/kubernetes/, or helm/chart/

  2. Add the function to the appropriate category class (e.g., ConversionFunctions.java)

  3. Register it in the HelmFunctions coordinator

  4. Add tests in the corresponding test class (e.g., Helm4FunctionsTest.java)