Update plugin meta.yaml spec documentation#150
Conversation
Signed-off-by: Angel Misevski <amisevsk@redhat.com>
README.md
Outdated
| Here is an overview of all fields that can be present in plugin meta YAML files. This document represents the current `v3` version. | ||
|
|
||
| ```yaml | ||
| apiVersion: # v2; v1 supported for backwards compatability |
There was a problem hiding this comment.
There is no v3. If you are thinking about the v3 path on the registry side, that is a separate version (and relates to registry design).
There was a problem hiding this comment.
How about describing this as "Version of the meta.yml file format" to prevent others from thinking the same as me.
There was a problem hiding this comment.
Great point -- I've addressed a few of these comments elsewhere already.
Will do :)
README.md
Outdated
| apiVersion: # v2; v1 supported for backwards compatability | ||
| publisher: # publisher name | ||
| name: # plugin name | ||
| version: # plugin version |
There was a problem hiding this comment.
The combination of publisher, name, version make up the id. Must they be globally unique?
There was a problem hiding this comment.
Semantically, a publisher cannot have two plugins with the same name and version, I don't believe this requires explicit documentation.
There was a problem hiding this comment.
Well, the fact that publisher/name/version is makes up the unique identifier is not obvious to a noob.
There was a problem hiding this comment.
Similarly though, I would not expect a user be surprised when releasing two identical plugins does not work. Are there any marketplaces/registries that allow this?
README.md
Outdated
| apiVersion: # v2; v1 supported for backwards compatability | ||
| publisher: # publisher name | ||
| name: # plugin name | ||
| version: # plugin version |
There was a problem hiding this comment.
What's the format of the version string?
There was a problem hiding this comment.
Anything you want, currently. We're currently moving to support latest as an alias to the newest version released.
There was a problem hiding this comment.
Thanks for the explanation, put it in the doc :-)
README.md
Outdated
|
|
||
| ```yaml | ||
| apiVersion: # v2; v1 supported for backwards compatability | ||
| publisher: # publisher name |
There was a problem hiding this comment.
Are there restrictions on the what can be contained here? Can the publisher contain stuff like '/'? Is there escaping when constructing the plugin id?
There was a problem hiding this comment.
I'll add explicit documentation here. I believe the requirement is alphanumeric + ., -, and _.
There was a problem hiding this comment.
Added regexes for these; to close the loop: publisher and name are alphanumeric plus '-', version can additionally contain '.'
| type: # plugin type; e.g. "Theia plugin", "Che Editor" | ||
| displayName: # name shown in user dashboard | ||
| title: # plugin title | ||
| description: # short description of plugin's purpose |
There was a problem hiding this comment.
How long, what should it contain?
There was a problem hiding this comment.
It should contain a description of what the plugin does; I don't think we have a limit on length.
| secure: # use secure version of protocol above | ||
| discoverable: # if false, no service is created for this endpoint | ||
| cookiesAuthEnabled: | ||
| type: |
There was a problem hiding this comment.
The meaning of this one is lost to time immemorial. Perhaps @sleshchenko can answer?
| discoverable: # if false, no service is created for this endpoint | ||
| cookiesAuthEnabled: | ||
| type: | ||
| path: |
There was a problem hiding this comment.
Should be API path but I can't track how it's used across the infrastructure backend.
| env: # list of env vars to set in sidecar | ||
| - name: | ||
| value: | ||
| volumes: # volumes required by plugin |
There was a problem hiding this comment.
Will this create volumes? How does it play with the volumes defined in a workspace config?
README.md
Outdated
| volumes: # volumes required by plugin | ||
| - mountPath: | ||
| name: | ||
| ports: # ports exposed by plugin |
There was a problem hiding this comment.
What's the relationship between "ports" and "endpoints"?
There was a problem hiding this comment.
Ports are exposed on a container; endpoints are exposed separately. The analogue is container ports and service ports -- should be familiar to people using k8s/openshift.
There was a problem hiding this comment.
"analogue" as in "will map to"? That would be useful info.
There was a problem hiding this comment.
Good point; will do.
| workspaceEnv: # optional; env vars for the workspace | ||
| - name: | ||
| value: | ||
| extensions: # optional; required for VS Code/Theia plugins; list of urls to plugin artifacts (.vsix/.theia files) -- examples follow |
There was a problem hiding this comment.
This is input to the plugin broker, right? How can the user find out which plugin file formats are supported? Shouldn't we mention the restriction on downloading from the vs code marketplace here?
There was a problem hiding this comment.
There aren't currently many restrictions here; the broker will download whatever you give it.
I hesitate to codify the VS Code marketplace limitation here but can add it if it is important.
Signed-off-by: Angel Misevski <amisevsk@redhat.com>
|
@tsmaeder Your review brings up a lot of great questions about the current |
Additionally make it clear that ports in containers refer to the Kubernetes concept. Signed-off-by: Angel Misevski <amisevsk@redhat.com>
3 participants
What does this PR do?
Updates the documentation around what we expect for
meta.yamls in the registry, to clarify issues around latest changes.@l0rd Please double check I got the current spec correct.