HIP for descriptions for custom completions

hips/hip-0008.md

@@ -0,0 +1,169 @@
+---
+hip: 0008
+title: "Add descriptions to custom completions"
+authors: [ "Marc Khouzam <marc.khouzam@montreal.ca>" ]
+created: "2020-11-14"
+type: "feature"
+status: "draft"
+---
+
+## Abstract
+
+Provide (optional) descriptions for helm's custom completions.
+
+The goal is to help users be more efficient by providing useful information
+when doing auto-completion.
+
+## Motivation
+
+Helm currently supports auto-completion for the following shells: `bash`, `zsh`,
+`fish`. Both the `zsh` and `fish` shells support descriptions for completions.
+
+For example, in the case of `zsh`:
+```
+$ helm s<TAB>
+search  -- search for a keyword in charts
+show    -- show information of a chart
+status  -- display the status of the named release
+```
+
+[The Cobra project][cobra project], which is used by Helm to define its
+commands and flags, automatically provides completion descriptions when
+completing those commands and flags.  Those descriptions are based on the usage
+information specified by Helm.  However, custom completions that are provided
+by helm itself currently don't include any descriptions. For example, when
+completing `helm status` it is helm that provides the list of releases, but
+this list does not include descriptions.
+```
+$ helm status n<TAB>
+nginx          nginx-ingress
+```
+
+Augmenting helm's custom completions with descriptions allows providing
+additional information to help users make their selection from the list of
+completions.
+
+## Rationale
+
+The completions for some helm arguments do not always provide sufficient
+information for a user to know which value to choose.  For instance, the
+name of a release is not always informative enough for the user to know
+which one to select.  For example:
+```
+$ helm upgrade ngin<TAB>
+nginx         nginx2
+```
+Clearly, in this case, the user needs to know the details of each release
+in advance as the difference between completion choices is not very helpful.
+
+## Specification
+
+Here are proposed descriptions for the different types of custom completions:
+* chart names (for 'install', 'pull', 'show *', 'template', 'upgrade')
+    * \<chart description>
+```
+$ helm install myrelease bitnami/c<TAB>
+bitnami/cassandra  -- Apache Cassandra is a free and open-source distributed database managemen
+bitnami/common     -- A Library Helm Chart for grouping common logic between bitnami charts. Th
+bitnami/consul     -- Highly available and distributed service discovery and key-value store de
+bitnami/contour    -- Contour Ingress controller for Kubernetes
+```
+As the chart description will often be too long to fit on a single line, the shell will truncate
+the description to fit the shell's window.  Note that each shell handles this case in its own way,
+where `zsh` truncates, while `fish` uses an ellipsis.
+
+* chart version (for '--version')
+    * App: \<app version>, Created: \<date>
+```
+$ helm pull bitnami/nginx --version 7.1.<TAB>
+7.1.0  -- App: 1.19.2, Created: September 24, 2020
+7.1.1  -- App: 1.19.3, Created: September 29, 2020
+7.1.2  -- App: 1.19.3, Created: October 2, 2020
+```
+* kubernetes context (for '--kube-context')
+    * \<kube cluster name>
+```
+$ helm --kube-context d<TAB>
+default  -- k3d-k3s-default
+dev      -- development
+```
+* helm environment variables (for 'env')
+    * \<value> (\<description of variable>)
+```
+$ helm env HELM_RE<TAB>
+HELM_REGISTRY_CONFIG    -- /me/Library/Preferences/helm/registry.json (Path to the registry configuration file)
+HELM_REPOSITORY_CACHE   -- /me/Library/Caches/helm/repository (Path to the file containing cached repository indexes)
+HELM_REPOSITORY_CONFIG  -- /me/Library/Preferences/helm/repositories.yaml (Path to the file containing repository names and URLs)
+```
+* plugin names (for 'plugin uninstall', 'plugin update')
+    * \<plugin description>
+```
+$ helm plugin uninstall <TAB>
+2to3        -- migrate and cleanup Helm v2 configuration and releases in-place to Helm v3
+fullstatus  -- provide status of resources part of the release
+```
+* release names (for 'get *', 'history', 'rollback', 'status', 'test', 'upgrade')
+    * \<chart name>-\<chart version> -> \<release status>
+```
+$ helm status <TAB>
+mynginx        -- nginx-6.0.5 -> superseded
+nginx-ingress  -- nginx-ingress-controller-5.4.4 -> deployed
+```
+* release revisions (for 'rollback', '--revision')
+    * App: \<app version>, Chart: \<chart name>-\<chart version>
+```
+$ helm rollback nginx-ingress <TAB>
+1  -- App: 0.34.1, Chart: nginx-ingress-controller-5.4.4
+2  -- App: 0.40.2, Chart: nginx-ingress-controller-5.6.10
+```
+* repo names (for 'repo remove' and completion of chart names)
+    * \<repo URL>
+```
+$ helm repo remove <TAB>
+bitnami  -- https://charts.bitnami.com/bitnami
+center   -- https://repo.chartcenter.io
+stable   -- https://charts.helm.sh/stable
+```
+* output formats (for '--output', '-o')
+    * \<format description>
+```
+$ helm status -o <TAB>
+json   -- Output result in JSON format
+table  -- Output result in human-readable format
+yaml   -- Output result in YAML format
+```
+
+Note that descriptions can be turned off by the user when generating the shell
+completion script using the `--no-descriptions` flag.
+
+## Backwards compatibility
+
+Not applicable to shell auto-completion. In fact, this allows us to implement
+some descriptions and still be able to modify them later if different ones are
+requested.
+
+## Security implications
+
+None
+
+## How to teach this
+
+The new descriptions will automatically appear when using auto-completion, so no
+special effort needs to be made to teach this new feature.
+
+## Reference implementation
+
+A PR will be opened to implement the proposed specification for descriptions of
+custom completions.
+
+## Open issues
+
+None.  
+
+It is worth clarifying that the bash shell does not support descriptions for
+auto-completion, so this feature will not apply to bash.  That being said, there
+is a [PR open on the Cobra project][cobra pr] that adds descriptions for bash
+completions.
+
+[cobra project]: https://github.com/spf13/cobra
+[cobra pr]: https://github.com/spf13/cobra/pull/1146