Krew plugin criteria #152
Krew plugin criteria #152
Conversation
Signed-off-by: Cornelius Weig <[email protected]>
k8s-ci-robot
added
the
cncf-cla: yes
k8s-ci-robot
added
the
size/M
|
Thanks for taking charge here. We definitely need this document, so this is gonna be a long PR. Styling-wise: I feel like if you can put the Guidances right next to the situations (maybe markdown table, maybe just a sub-bullet point) it would be easier to read and leave review-comments. |
Signed-off-by: Cornelius Weig <[email protected]>
|
Yeah, that looks so much nicer. Have you discussed about the plugin criteria during KubeCon? |
There was a problem hiding this comment.
Thanks for kicking the conversation off. I had a good conversation at KubeCon about plugins with @ahmetb too.
Left some inline comments.
I think the main observation is to make it clear about what the criteria are for. The title says "Krew plugin" but I don't think this is defined anywhere explicitly. This should make a clear distinction between the Krew index or Krew plugins and the open Kubectl plugins.
I'd also suggestion merging this with the Naming guide, as really the naming guide is probably a subset of these criteria.
doc/plugin-criteria.md
Outdated
|
|
||
| Krew is a `kubectl` plugin manager. | ||
|
|
||
| A plugin provides a technical solution to at least one _task_ concerning a problem around kubernetes. |
There was a problem hiding this comment.
The first paragraph (above) is talking about Krew. This paragraph jumps to talking about "A plugin", by which I take it to mean "A kubectl plugin". The description is then very opinionated.
I think it's fine to have strong opinions about what goes in the Krew index. I don't think it's OK to try and generalise that to the open plugin system that kubectl has. Anyone can create any plugin for kubectl that they want, simply by giving it a specific name and putting it on the path. Because of that the Krew index will always be a subset of available Kubectl plugins, which I think is fine.
I'm not sure if you want to define a "Krew plugin", or whether this should read something like "A plugin +in the Krew index+" or similar.
There was a problem hiding this comment.
Yes, I fully agree. We should make clear that this is about krew plugins only. Can't do it right now, but you're welcome to suggest better wording.
There was a problem hiding this comment.
I recommend the following wording:
The centralized Krew plugin index (
krew-indexrepository) holds plugins that are applicable to a broad set of kubectl users.A plugin in Krew plugin index must add new functionality or enhance the existing functionality in kubectl, or capsulate a common operator/developer workflow for higher productivity.
We don't want to exclude people being creative and trying interesting things.
There was a problem hiding this comment.
Yeah, I like the approach to argue from the user-basis as opposed to kubectl-centric.
doc/plugin-criteria.md
Outdated
| |----|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ||
| | 1. | The task is already solved by kubectl. | Mere command wrappers are not acceptable, as those are better covered by shell aliases. However, convenience and productivity improvements are welcome (examples: `konfig`, `change-ns`, `view-secret`) | | ||
| | 2. | The task provides a different solution to a problem which is also solved by kubectl. However, the task would be impossible or very hard to reproduce with kubectl alone. Examples: `access-matrix`, `get-all`, `mtail`, `tail` | In general welcome unless it overlaps significantly with other plugins or has a bad usability. | | ||
| | 3. | The task addresses a completely different problem than any of the kubectl subcommands, but is clearly focused on k8s. | Gray area. If the task fits well into `kubectl`, it may be accepted (for example `kubectl debug`). | |
There was a problem hiding this comment.
The example of kubectl debug would appear to be against the naming guidelines, in particular "Be Specific". It feels like the Login example provided there.
There was a problem hiding this comment.
+1 we rejected several plugins named debug.
A common task they do is: kubectl cp a busybox binary, kubectl exec to install busybox symlinks, then kubectl exec -- sh to drop user to a shell inside the container. Although I think we accepted one named pod-debug.
There was a problem hiding this comment.
Oops. I had #135 in mind, but forgot that the agreement was to change the name.
Changed to kubectl debug-pod.
doc/plugin-criteria.md
Outdated
| | 2. | The task provides a different solution to a problem which is also solved by kubectl. However, the task would be impossible or very hard to reproduce with kubectl alone. Examples: `access-matrix`, `get-all`, `mtail`, `tail` | In general welcome unless it overlaps significantly with other plugins or has a bad usability. | | ||
| | 3. | The task addresses a completely different problem than any of the kubectl subcommands, but is clearly focused on k8s. | Gray area. If the task fits well into `kubectl`, it may be accepted (for example `kubectl debug`). | | ||
| | 4. | The task is very dissimilar to common kubectl tasks and is not primarily focused on k8s. However, it can be useful in the k8s ecosystem. | Not acceptable. | | ||
| | 5. | The task is very dissimilar to common kubectl tasks and is not focused on k8s. Its general usefulness in the k8s ecosystem is questionable. | Not acceptable. | |
There was a problem hiding this comment.
Being arbiters if utility is bound to cause some friction. Usefulness is in the eye of the beholder. Homebrew hacks around this by saying packages have to be maintained by users, not by the original author. The gist being if a user is happy to maintain a package them by definition it's useful. Not saying Krew should follow the same pattern, but having guidelines which say "we decide based on what we think" might cause friction later.
There was a problem hiding this comment.
I agree that "usefulness" is rather subjective. But I think the krew index does need some form of filtering. Otherwise, where should the line be drawn? If there is no line (like for brew), krew would be come a mere package manager and not a kubectl package manager.
Maybe you have better ideas of what could be reasonable criteria?
doc/plugin-criteria.md
Outdated
|
|
||
| Usability | ||
| --- | ||
| Furter required acceptance criteria: |
doc/plugin-criteria.md
Outdated
| --- | ||
| Furter required acceptance criteria: | ||
|
|
||
| 1. Standard look & feel: Adheres to standard kubectl best practices and in particular uses consistent (abbreviated) flag names. For example: bad `--ns`, good `--namespace` + `-n`. |
There was a problem hiding this comment.
Would be good to link to a style guide here to avoid friction and nitpicking.
There was a problem hiding this comment.
Good point. @ahmetb do you know if such a document exists?
There was a problem hiding this comment.
Yeah we should probably write a separate "Style Guide for Plugins" document. We could easily fill it up.
|
Let's not merge all criteria into one document for now, it's harder to litigate all points in one PR. |
|
I am thinking we can check this into krew main repo instead, since this repo ships to every krew client machine, and we already have a docs/ in the main repo. |
doc/plugin-criteria.md
Outdated
|
|
||
| This task should be classified in one of the categories: | ||
|
|
||
| | # | Classification | Recommendation | |
There was a problem hiding this comment.
nit: (hope you won't hate me for saying this) I think if we actually do this part as an HTML table, we can also do 80-char word wrap and maintain this more easily:
<table>
<thead>
<tr>
<td>column</td>
<td>column</td>
</tr>
</thead>
<tbody>
<tr>
<td>column</td>
<td>column</td>
</tr>
</tbody>
</table>There was a problem hiding this comment.
No, I think this is absolutely necessary. Will do.
doc/plugin-criteria.md
Outdated
| | # | Classification | Recommendation | | ||
| |----|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ||
| | 1. | The task is already solved by kubectl. | Mere command wrappers are not acceptable, as those are better covered by shell aliases. However, convenience and productivity improvements are welcome (examples: `konfig`, `change-ns`, `view-secret`) | | ||
| | 2. | The task provides a different solution to a problem which is also solved by kubectl. However, the task would be impossible or very hard to reproduce with kubectl alone. Examples: `access-matrix`, `get-all`, `mtail`, `tail` | In general welcome unless it overlaps significantly with other plugins or has a bad usability. | |
There was a problem hiding this comment.
I think we can give detailed examples. Take this sentence:
For example:
tailplugin allows tailing logs from pods from a label selector, a namespace or all namespaces at once, whereaskubectl logscommand has more limited functionality.get-allplugin is a replacement forkubectl get allcommand which actually fetches only a subset of API resource types.
Are you referring to the idea to merge this with the naming guide? |
Argue user-centric instead of kubectl-centric. Signed-off-by: Cornelius Weig <[email protected]>
Signed-off-by: Cornelius Weig <[email protected]>
Signed-off-by: Cornelius Weig <[email protected]>
k8s-ci-robot
added
size/L
|
Thanks for doing the html migration, looks like we need to use full html i.e. I want to capture an additional criteria about plugins being more broadly usable to most Kubernetes users, but this is hard to measure and evaluate.
One of them feels right, where the other one doesn’t, and this is hard to measure. |
|
In the end, what you suggest always boils down to: how large is the userbase for setup XY. But even if we come up with an agreement what should be the acceptable number of users, how would we measure that in practice? Hence, I'm more with @garethr here who brought up the brew philosophy: if somebody maintains it, it's fine. (Of course it still needs to match the other to-be-determined criteria). What I could imagine to work is a whitelist of well-known k8s projects for which plugins may be submitted. For example: knative, istio, linkerd, tekton, jenkins-x, rook.io, and so on. Of course such a list needs to be curated and be kept up to date. By default, all incubating CNCF projects should be on that list too. |
Signed-off-by: Cornelius Weig <[email protected]>
| </tr> | ||
| <tr> | ||
| <td>3.</td> | ||
| <td>The task addresses a completely different problem than any of the kubectl subcommands, but is clearly focused on k8s.</td> |
There was a problem hiding this comment.
I think an indicator of this is:
Most users will use this tool as a kubectl plugin.
If this is the case, then it's probably more suitable. e.g. in case of helm vs kubectl helm, there's no need to make it a plugin, because it doesn't add anything to kubectl.
Worth adding.
There was a problem hiding this comment.
I've added that to the recommendation column. Was that what you intended?
doc/plugin-criteria.md
Outdated
|
|
||
| Usability | ||
| --- | ||
| Further required acceptance criteria: |
There was a problem hiding this comment.
I think we should relax this part a bit, and maybe make it optional to not to limit creativity too much.
There was a problem hiding this comment.
Do you meant to not talk about "required" criteria?
There was a problem hiding this comment.
I meant we should just remove the language that makes it "required". We can still list best practices, or develop a separate style guide.
There was a problem hiding this comment.
ok, makes sense.
Signed-off-by: Cornelius Weig <[email protected]>
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: corneliusweig The full list of commands accepted by this bot can be found here. The pull request process is described here
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
k8s-ci-robot
added
the
approved
Signed-off-by: Cornelius Weig <[email protected]>
Signed-off-by: Cornelius Weig <[email protected]>
|
@ahmetb I've added another recommendation to consider |
|
Issues go stale after 90d of inactivity. If this issue is safe to close now please do so with Send feedback to sig-testing, kubernetes/test-infra and/or fejta. |
k8s-ci-robot
added
the
lifecycle/stale
|
@ahmetb @ferhatelmas WDYT, should we give this another try or should I close this? |
|
/remove-lifecycle stale Let’s keep it open. Looks like we are gaining better confidence over time. We can take it in at some point. |
k8s-ci-robot
added
lifecycle/frozen
|
The This bot removes
You can:
Please send feedback to sig-contributor-experience at kubernetes/community. /remove-lifecycle frozen |
k8s-ci-robot
removed
the
lifecycle/frozen
|
The Kubernetes project currently lacks enough contributors to adequately respond to all issues and PRs. This bot triages issues and PRs according to the following rules:
You can:
Please send feedback to sig-contributor-experience at kubernetes/community. /lifecycle stale |
k8s-ci-robot
added
the
lifecycle/stale
|
The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs. This bot triages issues and PRs according to the following rules:
You can:
Please send feedback to sig-contributor-experience at kubernetes/community. /lifecycle rotten |
k8s-ci-robot
added
lifecycle/rotten
|
The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs. This bot triages issues and PRs according to the following rules:
You can:
Please send feedback to sig-contributor-experience at kubernetes/community. /close |
|
@k8s-triage-robot: Closed this PR. In response to this:
Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository. |
Hi @ahmetb @juanvallejo,
as you all know, krew-index currently has no criteria to apply for accepting or rejecting plugins. This creates friction for both contributors and maintainers:
So I put up this draft for plugin criteria to get the discussion going. It is an opinionated crude first draft and probably misses a lot of things. But maybe it helps nevertheless. Let me know what you think.
cc @garethr because you wanted to tune in