-
Notifications
You must be signed in to change notification settings - Fork 173
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #161 from VilledeMontreal/hip/compCustomDescriptions
HIP for descriptions for custom completions
- Loading branch information
Showing
1 changed file
with
169 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |