Implement versioning system

[uncenter]

This is a tricky one that I would love help brainstorming ideas for.

Requirements

Ultimately we need to:

• Allow users to specify a version in the schema URL (e.g. https://yazi-rs.github.io/schemas/vX.X.X/theme.json).
• Allow users to simply go off of the latest release (e.g. https://yazi-rs.github.io/schemas/latest/theme.json).
• Allow users to use schemas that match the latest commit (not sure what the URL would look like, maybe just what it is now - https://yazi-rs.github.io/schemas/theme.json - but that will cause issues when we initially implement this as right now that schema reflects the latest release. It could be https://yazi-rs.github.io/schemas/main/theme.json?).

Ideas

• A folder for each version (/schemas/latest/, schemas/v0.2.3/, schemas/main/)
  • PROS: As simple as it gets, near zero to no changes needed to the schema deploy workflow. Schemas from past versions can easily be edited too.
  • CONS: Gets overwhelming quickly, many different schema files containing mostly the same thing in different directories is kinda redundant and too large.
• ...

[sxyazi]

A folder for each version (/schemas/latest/, schemas/v0.2.3/, schemas/main/)

If we want to do version control, it seems we can only do it this way. I don't have a better idea...

[sxyazi]

Continuation of #15 (comment)

I have some questions:

• If we adopt this version control, what is the scheme URL contained in https://github.com/sxyazi/yazi/blob/main/yazi-config/preset/yazi.toml?
• And what is the URL contained in https://github.com/sxyazi/yazi/blob/v0.2.3/yazi-config/preset/yazi.toml?
• Why do you think version control would have less "debt" than my proposal (if I understand your meaning correctly)?

[uncenter]

• If we adopt this version control, what is the scheme URL contained in https://github.com/sxyazi/yazi/blob/main/yazi-config/preset/yazi.toml?

• And what is the URL contained in https://github.com/sxyazi/yazi/blob/v0.2.3/yazi-config/preset/yazi.toml?

Both of these would be https://yazi-rs.github.io/schemas/latest/yazi.json. We can put a note in the docs or add a line to the comment that explains how to pin a version or use the schema of the most recent commit to main.

• Why do you think version control would have less "debt" than my proposal (if I understand your meaning correctly)?

It just seems like a poor patchwork solution to a wider problem. It would work, but not in all cases, and ultimately I think we do want some sort of versioning system to handle the things I've mentioned previously: pinning a version, latest release vs most recent commit.

[sxyazi]

Both of these would be https://yazi-rs.github.io/schemas/latest/yazi.json.

I'm a bit confused, are you saying to use the latest release's scheme URL in the latest main (HEAD)? Wouldn't that still cause issues like #15 (comment)?

It just seems like a poor patchwork solution to a wider problem. It would work, but not in all cases, and ultimately I think we do want some sort of versioning system to handle the things I've mentioned previously: pinning a version, latest release vs most recent commit.

I'm not sure when it wouldn't work though, don't we still need to do this "patchwork" if we want to make "most recent commit" work? It seems like we're back to my proposal, or are there better ways to catch up with the latest main branch commit?

[uncenter]

I'm a bit confused, are you saying to use the latest release's scheme URL in the latest main (HEAD)? Wouldn't that still cause issues like #15 (comment)?

"latest" in that URL means latest release. "main" means most recent commit to main.

I'm not sure when it wouldn't work though, don't we still need to do this "patchwork" if we want to make "most recent commit" work? It seems like we're back to my proposal, or are there better ways to catch up with the latest main branch commit?

What do you mean? The schemas can exactly match the latest release and/or most recent main commit with no issues with this versioning system. Your proposal was to add some things and remove them later and added additional work to get the timing. This versioning eliminates that.

[sxyazi]

"latest" in that URL means latest release. "main" means most recent commit to main.

I know, want I say is using latest(rather than main) in this main file https://github.com/sxyazi/yazi/blob/main/yazi-config/preset/yazi.toml?

What do you mean? The schemas can exactly match the latest release and/or most recent main commit with no issues with this versioning system. Your proposal was to add some things and remove them later and added additional work to get the timing. This versioning eliminates that.

My proposal only considers the latest main branch (this target) and the latest release (the previous target). Things added first will not/should not be removed; what needs to be removed are fields that have been removed. Let's say:

Yazi 0.1 (latest release, the previous target)

has two fields, field1 and field2:

# yazi.toml
field1
field2

The schema looks like:

# our-scheme.json
field1
field2

Yazi 0.2 (HEAD, this target):

This upcoming target removes the existing field2 and adds a new field3:

# yazi.toml
field1
field3

We will add the new field3 to the schema file and add a comment for field2:

# our-scheme.json
field1
field2  # TODO: remove this field once Yazi 0.2 is released
field3 <-- added

This way, neither Yazi 0.1 nor Yazi 0.2 will throw an error. When we actually release Yazi 0.2, we remove field2, and field3 just stays there.

In short, before this target is released, we only add; after it is released, we only remove.

[uncenter]

If someone on Yazi v0.1 uses field3 they will NOT get an error even though that property isn't supported yet. That is considered a bug in the schema in my view.

[sxyazi]

Yep this is a potential issue with it, but it's much easier than version control - with version control, if we want to catch up with the latest changes in the main branch, we also need to do the same steps (or is there a better way?)

It also doesn't require switching URLs, if the latest main yazi.toml (this target) includes the main scheme URL (or is it latest?), when this target is released and becomes the previous target, do we need to modify it to a fixed URL so that there are no issues when users obtain the scheme of a previous version via a tag, such as https://github.com/sxyazi/yazi/blob/v0.2.3/yazi-config/preset/yazi.toml?

That is also my question in #17 (comment), I don't think it makes sense for both this target and the previous target to use the same latest scheme.

Having too many schemes is not conducive to our management and can confuse users. Therefore, this is a trade-off sacrificing consistency for lower costs, as we just to ensure eventual consistency.

[uncenter]

Yep this is a potential issue with it, but it's much easier than version control - with version control, if we want to catch up with the latest changes in the main branch, we also need to do the same steps (or is there a better way?)

What do you mean the "same steps"?

It also doesn't require switching URLs, if the latest main yazi.toml (this target) includes the main scheme URL (or is it latest?), when this target is released and becomes the previous target, do we need to modify it to a fixed URL so that there are no issues when users obtain the scheme of a previous version via a tag, such as sxyazi/yazi@v0.2.3/yazi-config/preset/yazi.toml?

latest as in latest release, main as in main branch. The preset configs in the yazi-config/preset directory will have latest as the version, which emulates the current behavior. This is a "sane" default, but it allows for people - as I've previously mentioned - to pin versions if needed or bump up to nightly/main branch schemas.

I don't think it makes sense for both this target and the previous target to use the same latest scheme.

This is what we currently have though lol.