Create versioned settings schema

[Trenly]

• I have signed the Contributor License Agreement.
• I have updated the Release Notes.
• This pull request is related to an issue.
  • Support Versioned Settings Schema #2963

Solves a minor annoyance I had where available settings aren't clear based upon client version. Requires some aka.ms link updates

• https://aka.ms/winget-settings.schema.json -> Point to Latest
• https://aka.ms/winget-settings.schema.1.29.0.json -> New link

---

Microsoft Reviewers: Open in CodeFlow

[JohnMcPMS]

This doesn't feel like it solves the underlying problem. Yes, we can have versioned schemas and URIs to those versions. But I don't know that it makes things any better. The default settings file always gets https://aka.ms/winget-settings.schema.json; if that remains static, what should it point to?

Alternatively, what strategy should be used?

1. Static default, single URI :: Where does it point?
2. Static default, multiple URIs :: Versioned and preview (latest)? Does winget generate the default settings file based on its current version? Or is it up to users to fall back to a specific version?
3. Dynamic default, multiple URIs :: Versioned aka.ms and preview raw-blob targeting built commit? Winget checks settings schema when loading and rewrites it if it doesn't match expected?
4. Dynamic default, targets local file :: Packaged winget ships the schema file and the default settings file is generated to point to it? Unfortunately, there isn't a way to get a static default as the OS doesn't create a version-less symlink that it keeps updated. So this would have to do the rewrite to point to the local file (and worse, it breaks when you update but haven't run winget yet vs just getting an old schema with option 3).

We could actually do Option 3 without any additional aka.ms link management (which is all manual unfortunately). We just always use a commit specific URI rather than the aka.ms link. That wouldn't even require maintaining distinct files.

I guess my comment can be boiled down to: We need to agree on a design before we start implementing. That design should cover the entire ecosystem, not just the files in GitHub.

[Trenly]

As far as I can tell, the schema doesn't actually inform anything on the client - it's used purely for intellisense when users are authoring their settings. This is why I assumed that simply having the files updated at GitHub would solve the "issue" here, since the schema doesn't affect the behavior of the client - that's all done through the settingmapping specializations. I'm of the opinion that doesn't need to change - the static URI in settings can always point to the latest like it currently does.

While I do see value in point 2 that you brought up, it could easily be taken separately as there isn't an impact to behavior.

[JohnMcPMS]

If the goal is just to have a URI that points to older schemas, you can use the release branches for that:
https://raw.githubusercontent.com/microsoft/winget-cli/release-v1.28/schemas/JSON/settings/settings.schema.0.2.json

I don't have a big problem with dropping the version from the file name, but it would create a point at which you need to know that the file name changes across the release branches.

Maybe I was wrong on getting a design: What problem are we actually trying to solve?

[Trenly]

What problem are we actually trying to solve?

In my mind, the problem, if you want to even call it that since it isn't really one, is a lack of clarity on which settings are "new" between versions and / or which settings can be used with any given client version. The versioned URIs from the release branches may make sense, but it's some additional hunting as opposed to seeing settings.schema.1.28 and settings.schema.1.29 in the file tree.

I do understand your view though - just because the client doesn't use the schema today doesn't mean it wouldn't ever be used in the future. In which case, it is important to think about possible future designs

[JohnMcPMS]

Would an update to the documentation .md with versioning history be sufficient then?

[florelis]

Could we add a tag to the property descriptions with the supported versions?
Like

      "properties": {
        "autoUpdateIntervalInMinutes": {
          "description": "[>=v1.0] Number of minutes before source update",
          "type": "integer",
          "default": 5,
          "minimum": 0,
          "maximum": 43200
        }

Although it depends on the editor showing you the description and may be too much noise.

[JohnMcPMS]

Could we add a tag to the property descriptions with the supported versions? Like

      "properties": {
        "autoUpdateIntervalInMinutes": {
          "description": "[>=v1.0] Number of minutes before source update",
          "type": "integer",
          "default": 5,
          "minimum": 0,
          "maximum": 43200
        }

Although it depends on the editor showing you the description and may be too much noise.

This doesn't show things like adding a new enum value later on, but for the property level it could work. I would just use the introduced version without the comparison operator for brevity (unless we remove a setting in the future, it would always be >=. So "description": "[1.0] Number of minutes before source update",

[Trenly]

All great ideas. Another question would be intellisense - if a user is sticking at the older version for some reason, intellisense wouldn't hide the properties from newer versions, but using the description for a version indicator could provide them indication of if / when a setting was supported.