check for plugins file schema version and type

[VinozzZ]

What does this change

Previously, the SchemaType and SchemaVersion are not parsed or validated. This PR adds the corresponding logic to properly process these fields

What issue does it fix

Notes for the reviewer

Put any questions or notes for the reviewer here.

Checklist

• Did you write tests?
• Did you write documentation?
• Did you change porter.yaml or a storage document record? Update the corresponding schema file.
• If this is your first pull request, please add your name to the bottom of our Contributors list. Thank you for making Porter better! 🙇‍♀️

Reviewer Checklist

• Comment with /azp run test-porter-release if a magefile or build script was modified
• Comment with /azp run porter-integration if it's a non-trivial PR

[carolynvs]

Since this is changing the file format used from what was just published in v1.0.5, we'll need to communicate that this is a breaking change and update the release notes on 1.0.5 to call out that it's a bad release effectively.

In addition to the usual announcements, since this is a breaking change (and a bad release), you should draft a blog post to go out at the same time as the new release that explains what went wrong, which version to use, and provides an explanation of the install multiple plugins feature. I recommend saying that's its a great way to quickly set up your Porter environment with your required plugins so that people get an idea of when you would use this feature. Probably don't mention the Porter Operator change that caused us to want this feature since it's not shipped yet, so let's focus on how people can use it right now.

[carolynvs]

When --version is empty, it defaults to latest so I'm not sure I get what this is checking for or guarding against? The error message just says that they can't specify --version at all so can't we just stick with the original check that version was specified?

[VinozzZ]

When no version is specified by users, the o.Version is default to latest. The original check would fail bc the o.Version is not empty.
The check here is to guard that users didn't try to set a version value through the flag. o.Version should not have value other than "latest" or empty

[carolynvs]

Thanks! I didn't realize that we were defaulting to "latest" so early, I'm assuming it's the flag default. Makes sense! 👍

[carolynvs]

I just remembered that we are missing schemaType validation on our other resources. I had created a branch to fix that and then got pulled off onto other things and forgot to submit a PR.

Let's do a check here for the schemaType as well, so that if they enter in a value other than what's expected, we don't try to process the file further. For example, they accidentally pass a bundle or installation file to the -f parameter.

https://github.com/carolynvs/porter/blob/ea694aa668a448eb2293775da5f5cfda3567214f/pkg/manifest/manifest.go#L185-L187

I'll submit my PR afterwards that adds the check to the other resources.

[carolynvs]

This default shouldn't be defined here. I assume you meant to define it directly on schemaVersion?

[carolynvs]

I don't think this is how the properties json schema field works for objects. Have you tested this against the json schema validator (https://www.jsonschemavalidator.net/) with both matching and incorrect schema to make sure it's correct?

Here is how I have defined an object with unknown keys in porter elsewhere (for custom action metadata):

https://github.com/getporter/porter/blob/2aa80a6670bd0aac7284cb8f5ad375b6b44b3365/pkg/schema/manifest.schema.json#L417C6-L421

[carolynvs]

I like to give the user hints that will show up in the hover text / documentation that will help them understand how to fill out the file better:

Suggested change

	"description": "The version for the plugin.",
	"description": "The version for the plugin. Defaults to latest when unspecified",

[carolynvs]

Suggested change

	"description": "The URL of an atom feed where the plugin can be downloaded.",
	"description": "The URL of an atom feed where the plugin can be downloaded. Defaults to the official Porter plugin feed.",

[carolynvs]

This field is hard to guess, so I always like to include an example of how to download from github releases:

Suggested change

	"description": "The URL from where the plugin can be downloaded",
	"description": "The URL from where the plugin can be downloaded. For example, https://github.com/MChorfa/porter-helm3/releases/download",

[carolynvs]

It would help to give people a hint that the field names under plugins should be the name of the plugin

Suggested change

	"description": "The definition of plugins to install",
	"description": "A map of plugins to install, keyed by the plugin name",

[carolynvs]

Looks great!

This reminds me that we need to update the porter vs code extension to check for schemaType and apply the proper json schema to the current document, e.g. if the open document is for porter and has "schemaType: Plugins", then vs code should apply this plugins json schema so that the user gets autocomplete.

I'll create another issue to work out the details but wanted to let you know how this schema will be used elsewhere too. 👍

[carolynvs]

Here's the issue to track showing autocomplete using our other json schema documents: getporter/vscode-extension#47