I have a proposal and I want to run by @grafana-community/helm-charts-maintainers before I open the PRs. Apologies ahead of time for the long read, but I thought it was better to walk you through my thought process that led me to proposing a larger change.
@jkroepke and I were talking about a desire to not to have remake helm-docs as often. We both concluded that removing the following sections from all readme.md.gotmpl files makes sense.
{{ template "chart.versionBadge" . }}
{{ template "chart.typeBadge" . }}
{{ template "chart.appVersionBadge" . }}
{{ template "chart.valuesSection" . }}
Additionally, I think it would also make sense to remove these sections due to Github Actions jobs.
{{ template "chart.maintainersSection" . }}
{{ template "helm-docs.versionFooter" . }}
For the maintainers, it's because helm-docs generates a table which uses the headers | Name | Email | Url |. The Url field name doesn't pass super-linter's Natural Language linting. It mandates that the string be changed to URL which we can't do, at least not without a upstream change to helm-docs. Even if it got fixed, I don't feel like it adds much value for users. So at present we've whitelisted the url string from Natural Language linting. I want to revert this if possible.
For the versionFooter, #60 is a work in progress that will diff helm-docs' desired state against actual state. It will leverage a github actions job for installing helm-docs which I strongly suspect will be auto-bumped via renovate. This means every time helm-docs is bumped, all of our values files would have to be re-created. That's a hard pass from me, especially for something that's purely cosmetic. Additionally, #62 implements a Makefile that adds a make helm-docs command which (at present) has renovate auto-bumping the version as well which causes the same issue.
So removing the noise was the first step in my thought process. My second step was "while I'm here" why not standardize our helm-docs templating a little bit. It's not really necessary and I wouldn't be upset at all if it didn't happen, but I thought it'd be worth a peek to see what comes out of it. So I started reviewing all of our current readme files and drafting a standard. It's quite simple mostly just removing what I mentioned above. I tried to stick to enforcing a standard on the top half and anything else chart-specific at the bottom. What I think you'll find here is that the draft really isn't all changing much after all the above sections are removed. Perhaps a few Header name changes and removal of empty fields.
draft standard
# {{ .Name }} Helm Chart # .Name isn't capitalized, perhaps it'd be better to not template it as to match current Camel Case
{{ template "chart.description" . }}
{{ template "chart.sourcesSection" . }}
{{ template "chart.requirementsSection" . }} # also includes the .dependencies section. None of our current charts have them which leads to only showing `Kubernetes => 1.25.0`, however Loki does have them and so it's kinda helpful.
## Installing the Chart
### OCI Registry
OCI registries are preferred in Helm as they implement unified storage, distribution, and improved security.
It does lack some features like the native ability to search chart versions.
For production however, OCI is recommended.
```console
helm install RELEASE-NAME oci://ghcr.io/grafana-community/helm-charts/{{ .Name }}
```
### HTTP Registry
```console
helm repo add grafana-community https://grafana-community.github.io/helm-charts
helm repo update
helm install RELEASE-NAME grafana-community/{{ .Name }}
```
## Uninstalling the Chart
To removes all of the Kubernetes objects associated with the Helm chart release:
```console
helm delete RELEASE-NAME
```
# Changelog
link to changelog.md # planned feature
=== above this line is standardized, below is freeform per-chart ===
# Upgrading
Notes on Major releases. Deeper description (than changelog) of changes made, motivation for change, and required actions
# Configuration
I saw people using this for either sharing common config examples or discussing common hurdles
That brings me to my final proposal. After looking over my final draft, the only section left that's ever even remotely likely to change is the requirements. Which is kinda mission accomplished; that was the initial goal. But it leaves me wondering if there's any value left in templating it? It'd be certainly be a simpler workflow to remove it.
I have a proposal and I want to run by @grafana-community/helm-charts-maintainers before I open the PRs. Apologies ahead of time for the long read, but I thought it was better to walk you through my thought process that led me to proposing a larger change.
@jkroepke and I were talking about a desire to not to have remake helm-docs as often. We both concluded that removing the following sections from all readme.md.gotmpl files makes sense.
Additionally, I think it would also make sense to remove these sections due to Github Actions jobs.
For the maintainers, it's because helm-docs generates a table which uses the headers
| Name | Email | Url |. TheUrlfield name doesn't pass super-linter's Natural Language linting. It mandates that the string be changed toURLwhich we can't do, at least not without a upstream change to helm-docs. Even if it got fixed, I don't feel like it adds much value for users. So at present we've whitelisted the url string from Natural Language linting. I want to revert this if possible.For the versionFooter, #60 is a work in progress that will diff helm-docs' desired state against actual state. It will leverage a github actions job for installing helm-docs which I strongly suspect will be auto-bumped via renovate. This means every time helm-docs is bumped, all of our values files would have to be re-created. That's a hard pass from me, especially for something that's purely cosmetic. Additionally, #62 implements a Makefile that adds a
make helm-docscommand which (at present) has renovate auto-bumping the version as well which causes the same issue.So removing the noise was the first step in my thought process. My second step was "while I'm here" why not standardize our helm-docs templating a little bit. It's not really necessary and I wouldn't be upset at all if it didn't happen, but I thought it'd be worth a peek to see what comes out of it. So I started reviewing all of our current readme files and drafting a standard. It's quite simple mostly just removing what I mentioned above. I tried to stick to enforcing a standard on the top half and anything else chart-specific at the bottom. What I think you'll find here is that the draft really isn't all changing much after all the above sections are removed. Perhaps a few Header name changes and removal of empty fields.
draft standard
That brings me to my final proposal. After looking over my final draft, the only section left that's ever even remotely likely to change is the requirements. Which is kinda mission accomplished; that was the initial goal. But it leaves me wondering if there's any value left in templating it? It'd be certainly be a simpler workflow to remove it.