Create a schema for .version files

[HebaruSan]

Currently the format of .version files has two de facto definitions:

• The old README on @cybutek's web site
• The current KSP-AVC code

(There are two other versions of the format that are simply out of date and therefore less important, see #25.)

The current KSP-AVC supports properties that aren't listed on the web site, and this can only be discovered by reading the C# code. The lack of a clear standard creates two problems:

• It's difficult to create a .version file correctly, since the full list of available properties and their meanings are not listed anywhere
• Once created, it's difficult to tell whether a .version file is valid

To try to help with these issues, this PR codifies the current KSP-AVC code in a JSON schema file, based on work originally done by @janbrohl and mentioned in KSP-CKAN/CKAN#1768. This file can be used to validate .version files and print errors if they aren't valid (potentially helping with #1, functionality not included in this pull request). This can be done with tools like Python's jsonschema module or C#'s NJsonSchema module. It is also our hope to someday offer it to mod authors via a tool like Github Action: Validate JSON, potentially warning about errors before modules are even released.

I had to guess on the descriptions of some of the recently added properties, so please feel free to make edits as needed.

PLEASE maintain this going forward! It should be updated anytime a new property is added, changed, or removed, ideally in the same pull request.

[HebaruSan]

@DasSkelett, the schema is here in case you want to try it out.

[linuxgurugamer]

I appreciate your work. You seem to be missing the latest change to support checking file locations, I'll update this and then ask you to review it. I think I understand it, but it's not something I've dealt with before

[linuxgurugamer]

Oh, I just realized that the latest change to the schema is implemented in a different program, which is why you didn't see it.

[linuxgurugamer]

I've updated the schema, could you take a look at it. The one thing I'm not sure about is having a wildcard and an "or" in the labels(?) . Full description of what this is for is on this page: https://github.com/linuxgurugamer/KSP_Install_Validator

Thanks

[HebaruSan]

Is it too late to improve the design of that piece? The INSTALL_LOC_1 suffix format is really messy and bad for data integrity. If multiple values are needed, then INSTALL_LOC should just be defined as an array, you can easily supply only one array element if needed.

[HebaruSan]

To clarify what I'm talking about:

"INSTALL_LOC": [
    {
        "NAME":     "modname",
        "PATH":         "path",
        "DIRECTORY":    "dirName",
        "FILE":         "fileName",
        "MESSAGE":      "message to display"
    },
    {
        "NAME":     "modname",
        "PATH":         "path",
        "DIRECTORY":    "dirName",
        "FILE":         "fileName",
        "MESSAGE":      "message to display"
    }
]

[DasSkelett]

@linuxgurugamer I have worked out a basic GitHub workflow setup that uses the schema to validate a .version file in a repository, see this PR in my fork: https://github.com/DasSkelett/KSPAddonVersionChecker/pull/1

I thought about making this a full GitHub Action, which mod authors can activate in their repo to validate all version files found in it by using the schema of this repo's master branch.

This should help mod authors to keep the .version file syntactically correct (and reduce the amount of PRs the CKAN team has to do to fix them again :D)

What do you think of this idea?

[linuxgurugamer]

@DasSkelett I think it's a great idea. But you will need to have explicit instructions for people to set it up, I would guess that most have no idea what a GitHub Action is

Regarding the INSTALL_LOC, I'll take a look. Never thought about it that way, makes sense. So far only a few mods are using it (mostly mine), so it won't be a problem to change

[DasSkelett]

@linuxgurugamer great! I've created the Action here: https://github.com/DasSkelett/AVC-VersionFileValidator. It has basic functionality and is working. @HebaruSan thankfully offered to test it, so here is what it looks like in actual mod repositories:

• Workflow file
• A validation run

This is how the workflow file could look like for the KSP-AVC repository itself: https://github.com/DasSkelett/KSPAddonVersionChecker/blob/workflow-using-action/.github/workflows/VersionFileValidation.yml It excludes all the test .version files in TestCases, because I think some of them are intentionally wrong. (It also tracks the dev branch of the action for testing purposes). I can do a PR to add it to this repository if you want.

The setup should be pretty straightforward, there are instructions in the README. I am also going to add some pictures for those wanting to add it directly via GitHub.