docs: minor corrections and adding linting and mutability considerations

Signed-off-by: Andrew Shoell <mrlunchbox777@gmail.com>

Author: mrlunchbox777

hips/hip-0027.md

@@ -72,9 +72,19 @@ The choice of `.DeployedChart` as the object name was made after considering sev
 - It works clearly for both upgrade and rollback scenarios
 - It follows the established pattern of top-level template objects like `.Chart`, `.Release`, and `.Values`
 
-### Making `.DeployedChart` nil for Fresh Installs
+### Always Available as Template Object
 
-When no deployed release exists (during `helm install`), `.DeployedChart` is set to `nil` rather than an empty struct or having default/zero values. This decision was made because:
+`.DeployedChart` is always present in the template context, even when it contains no data (nil). This design decision ensures:
+
+- **Consistent template behavior**: Templates don't need conditional logic to check if the object exists vs. if it has data
+- **Follows Go template conventions**: nil is the idiomatic way to represent absence of data
+- **Simplifies template code**: `{{ if .DeployedChart }}` works in all scenarios
+- **Enables testing**: Templates using `.DeployedChart` can be tested with `helm template` without undefined variable errors
+- **Prevents template failures**: References to `.DeployedChart` don't cause rendering errors
+
+### Making `.DeployedChart` nil When No Deployed Release Exists
+
+When no deployed release exists, `.DeployedChart` is set to `nil` rather than an empty struct or having default/zero values. This decision was made because:
 
 - It follows idiomatic Go and template patterns for representing absence of data
 - It enables simple, natural existence checks: `{{ if .DeployedChart }}`
@@ -93,7 +103,7 @@ This decision provides:
 
 ### Available During Upgrade and Rollback Operations
 
-`.DeployedChart` is always available as a template object but is populated with chart metadata only during `helm upgrade` and `helm rollback` operations when a deployed release exists in the cluster. In all other scenarios, `.DeployedChart` is nil.
+`.DeployedChart` is populated with chart metadata only during `helm upgrade` and `helm rollback` operations when a deployed release exists in the cluster. In all other scenarios, `.DeployedChart` is nil.
 
 **Populated with chart metadata:**
 - `helm upgrade` (when upgrading an existing release)
@@ -107,14 +117,6 @@ This decision provides:
 - `helm upgrade --dry-run` - No cluster access during dry-run
 - When `--disable-deployed-chart` flag is used - Explicitly disabled
 
-The object is always present in the template context to ensure templates can be written consistently across all operations. Chart authors can rely on `.DeployedChart` being a valid object reference (though it may be nil) without worrying about undefined variable errors.
-
-**Why always available but sometimes nil:**
-- Consistent template behavior - templates don't need to conditional logic to check if the object exists vs. if it has data
-- Follows Go template conventions - nil is the idiomatic way to represent absence of data
-- Simplifies template code - `{{ if .DeployedChart }}` works in all scenarios
-- Enables testing - templates using `.DeployedChart` can be tested with `helm template` without errors
-
 ### Chart Metadata Only (Not Full Release Data)
 
 This proposal intentionally limits `.DeployedChart` to chart metadata and does not expose the full release object, which would include previous values, previous manifest, or detailed release metadata (revision number, timestamps, status, etc.).
@@ -178,7 +180,7 @@ Chart authors who need to inspect actual cluster state should use the `lookup()`
 
 ### Dry-Run and Template Operations
 
-`.DeployedChart` is always available as a template object but is always nil during `helm template` and dry-run operations (`helm install --dry-run`, `helm upgrade --dry-run`) because these commands are intentionally cluster-agnostic and should remain deterministic without cluster context.
+`.DeployedChart` is always nil during `helm template` and dry-run operations (`helm install --dry-run`, `helm upgrade --dry-run`) because these commands are intentionally cluster-agnostic and should remain deterministic without cluster context.
 
 The object is present (but nil) to ensure templates that reference `.DeployedChart` don't fail with undefined variable errors during templating and dry-run operations.
 
@@ -338,7 +340,7 @@ When this flag is set, `.DeployedChart` will be nil regardless of whether a depl
 ### Behavior During Different Operations
 
 | Operation | `.DeployedChart` Availability | `.DeployedChart` Value |
-|-----------|------------------------------|----------------------|
+|-----------|-------------------------------|------------------------|
 | `helm install` | Always available | Always `nil` (no deployed release) |
 | `helm upgrade` (first install) | Always available | `nil` (no deployed release) |
 | `helm upgrade` (actual upgrade) | Always available | Populated with deployed chart metadata |
@@ -348,7 +350,7 @@ When this flag is set, `.DeployedChart` will be nil regardless of whether a depl
 | `helm template` | Always available | Always `nil` (no cluster context) |
 | `helm install --dry-run` | Always available | Always `nil` (no cluster context) |
 
-**Note:** The object is always present to prevent template errors when referencing `.DeployedChart`, even when it contains no data.
+**Note:** The object is always present in the template context to prevent template errors when referencing `.DeployedChart`, even when it contains no data.
 
 ## Backwards Compatibility
 
@@ -400,7 +402,7 @@ This proposal has been designed with security considerations in mind:
 The following documentation should be added or updated:
 
 **1. Template Objects Reference:**
-Add `.DeployedChart` to the list of built-in objects available in templates, with clear documentation about when it's available and when it's nil.
+Add `.DeployedChart` to the list of built-in objects available in templates, with clear documentation about when it's populated and when it's nil.
 
 **2. Upgrade Guide:**
 Create a guide titled "Implementing Version-Aware Upgrades" that covers:
@@ -531,6 +533,14 @@ data:
 - How to test templates that use `.DeployedChart`
 - Common pitfalls and how to avoid them
 
+**6. Chart Linting:**
+Consider updating `helm lint` to provide helpful warnings for common issues:
+- Warn if templates use `.DeployedChart` without nil checks (e.g., direct field access without `{{ if .DeployedChart }}`)
+- Suggest best practices for version comparison logic
+- Flag potential issues with upgrade-specific resources that might not be cleaned up
+
+This would help chart authors catch potential issues early in development and promote correct usage patterns.
+
 ## Reference Implementation
 
 A reference implementation will be provided in a future pull request to the Helm repository. The implementation will:
@@ -555,24 +565,67 @@ The following ideas were considered during the design of this HIP but were ultim
 - Complexity concerns (chart metadata is sufficient for most use cases)
 - Can be added later if compelling use cases emerge
 
-### Making Available During `helm install`
+### Different Naming Conventions
+
+**Ideas considered:**
+- `.PreviousChart` - Ambiguous for rollbacks ("previous" could mean different things)
+- `.InstalledChart` - Confusing with the chart currently being installed
+- `.CurrentChart` - Ambiguous (which chart is "current"?)
+- `.Release.Deployed.Chart` - Unnecessarily nested, breaks consistency with `.Chart`
+- `.OldChart` - Informal and ambiguous
+
+**Rejection Reason:** `.DeployedChart` is the clearest and most consistent with Helm terminology. "Deployed" unambiguously means "what's currently running in the cluster."
+
+### Exposing Only Version Strings
+
+**Idea:** Only expose `.DeployedVersion` and `.DeployedAppVersion` as simple strings instead of the full chart object.
 
-**Idea:** Make `.DeployedChart` unavailable (not present in template context) during fresh installs.
+**Rejection Reason:**
+- Inconsistent with `.Chart` object structure
+- Prevents access to other useful metadata (type, deprecated status, annotations)
+- Would need to be expanded later anyway if more fields are needed
+- Simpler to reuse existing Chart metadata structure
+
+### Environment Variable or Config File for Opt-Out
+
+**Idea:** Control the feature via environment variable (`HELM_DISABLE_DEPLOYED_CHART`) or Helm configuration file instead of CLI flag.
 
 **Rejection Reason:**
-- Would cause template errors when templates reference `.DeployedChart` during install
-- Inconsistent behavior - templates would need to handle both "object doesn't exist" and "object is nil" cases
-- Makes testing harder - templates would fail during `helm template` with undefined variable errors
-- Having the object always present but nil is more idiomatic and user-friendly
-- Templates written with `{{ if .DeployedChart }}` work correctly in all scenarios
+- Less explicit than a CLI flag
+- Harder to see in scripts and documentation
+- Doesn't follow Helm's pattern of operation-specific flags
+- Could cause confusion if set globally but not desired for specific operations
+- Environment variables can be accidentally inherited in unexpected contexts
 
-### Making Available During `helm template`
+### Querying Cluster During `helm template`
 
-**Idea:** Make `.DeployedChart` unavailable (not present in template context) during `helm template`.
+**Idea:** Allow `.DeployedChart` to be populated during `helm template` by querying the cluster if kubectl context is available.
 
 **Rejection Reason:**
-- Would cause template errors when templates reference `.DeployedChart`
-- Violates the design principle that `helm template` should work for all valid templates
-- Makes development harder - chart authors couldn't validate template syntax
-- Having the object present but nil allows templates to render successfully
-- A future mock/plugin system is a better solution for providing test data
+- Violates the design principle that `helm template` should be cluster-agnostic
+- Would make template rendering non-deterministic
+- Could cause security issues if templating in one environment with data from another
+- Would require cluster credentials during templating operations
+- A future mock/plugin system is a better solution for testing
+
+### Making `.DeployedChart` Mutable
+
+**Idea:** Allow templates to modify `.DeployedChart` values.
+
+**Rejection Reason:**
+- Template objects should be read-only to maintain determinism
+- Would create confusion about source of truth (is it from the cluster or from template modifications?)
+- Could lead to complex bugs and security issues
+- Violates Helm's template rendering model where templates are purely declarative
+- No clear use case that couldn't be better solved with template variables
+
+## Open Issues
+
+None at this time. This HIP is ready for community review and feedback.
+
+## References
+
+- [Helm Built-in Objects Documentation](https://helm.sh/docs/chart_template_guide/builtin_objects/)
+- [Helm Template Functions and Pipelines](https://helm.sh/docs/chart_template_guide/functions_and_pipelines/)
+- [Go Template Documentation](https://pkg.go.dev/text/template)
+- [Semantic Versioning 2.0.0](https://semver.org/)