Rethink how ZLS maintains backwards compatibility

[Techatrix]

The conclusion

ZLS has the following compatibility requirements:

• A tagged release of Zig or ZLS must be used with the same tagged release of Zig or ZLS
• A master/nightly build of ZLS requires master/nightly build of Zig

A master/nightly build of ZLS may be backwards compatible with older Zig versions (like the latest tagged release) but this is done as a best effort and may break at any time. If you rely on this behavior, your are destined to have incompatible Zig and ZLS versions at some point.

---

This has partially be brought up in #1000 and #1019

With the numerous breaking changes to the Zig language and its build system, it became harder to maintain compatibility with older Zig versions. This issue is only going to get worse as more versions are released and Zig's development accelerates.

I think its time to discuss ZLS's plan on how its going maintain compatibility with Zig.
Its harder to make a decision without knowing how many people are going to be affected by certain changes.
How many people use a pre 0.10.x release of Zig with ZLS master?
How many people use ZLS master compared a tagged release?
What version(s) do Zig projects tend to require?
How quickly do projects transition to new versions of Zig?

Despite that, here are some possibilities i could think of:

Strict

ZLS master only maintains compatibility with Zig master.
A tagged release of ZLS is only compatible with the same tagged release of Zig.

Relaxed

ZLS master can only be compiled with Zig master and is compatible with Zig master and the the latest tagged release of Zig.
A tagged release of ZLS must be compiled with and is only compatible with the same tagged release of Zig.

Split branches

We take the Strict Proposal but also maintain separate branch of ZLS that backports changes while maintaining compatibility with the latest tagged release of Zig.

[leecannon]

This is just me writing my thoughts down, anything im missing or you disagree with let me know and I will update it.

Strict

Pros:

• Simpler code
• Less chance for bugs
• Reduced maintenance burden

Cons:

• People on tagged releases of Zig have to wait for a Zig release cycle to get new ZLS features.
• People who use different versions of Zig for different projects now also need to switch between ZLS versions (can the extension be made smart enough to make this not painful?)

Relaxed

Pros:

• Single binary supports wide range of Zig versions (even if your stuck on a specific commit of master instead of a release, for 2 months last year I could not update Zig past a specific commit without hitting a blocking issue)

Cons:

• Code is complicated by being forced to deal with the differences between Zig versions
• More chance of bugs and regressions
• More work
• Upon tagging a new release the code would need to be cleaned up to remove the compatibility logic for the previous release (as we only want to support master and the latest release)

Split Branches

Pros:

• The main branch is nice and clean
• The tagged release support branch could be cleaner than the same code under the relaxed model as in the relaxed model both master and release code is intertwined

Cons:

• More work
• Depending on the amount of changes between Zig releases (which is only going to speed up) the chances for merge conflicts when trying to backport is very high even for changes that are the same for master and the tagged release branch
• People on tagged releases of Zig have to wait for a Zig release cycle to get new ZLS features.
• People who use different versions of Zig for different projects now also need to switch between ZLS versions (can the extension be made smart enough to make this not painful?)

[SuperAuguste]

To be honest, I really like the strict approach, at least for the moment. Because Zig is pre-1.0, it's inherently unstable and fast-moving. I think that we could take this approach until 1.0 is reached and then switch to the relaxed approach. The split branches approach seems untenable.

[leecannon]

I agree with you, it was all well and good doing a little bit of comptime magic in build_runner.zig to support renamed types, slightly changed arguments and simple things like that, but the changes that are starting to come through now are much more significant.

[leecannon]

In order to go with the strict approach the vscode extension will need some way of downloading and choosing between different versions of ZLS.

[yozachar]

I see this warning:

Zig '0.11.0' is older than ZLS '0.12.0-dev.54+b9b5d1c'. Update Zig to avoid unexpected behavior.

Related?

In order to go with the strict approach the vscode extension will need some way of downloading and choosing between different versions of ZLS.

I guess developers like to use tools such as asdf / rtx (at least I do) to manage multiple versions of programs. Re-implementing that logic won't be necessary, instead improving selection of installed zig version(s) might be apt.

[Techatrix]

In order to go with the strict approach the vscode extension will need some way of downloading and choosing between different versions of ZLS.

that issue is being tracked here.

[leecannon]

Now that ziglang/vscode-zig#138 is merged the main motivation of #1411 is gone (at least for vscode users).

As we are providing specific versions of zls for specific versions of zig now, is there any reason for us to keep zig version specific build runners?

[Techatrix]

Even though the main motivation is gone, I still believe there is use in keeping this feature. ZLS master contains numerous bug fixes and improvements over older tagged releases. So until there is something like a breaking syntax change that would prevent this use case, I would suggest to keep #1411.

[Techatrix]

I don't think there is any need to leave this issue open any longer. Here is how it looks:

ZLS has the following compatibility requirements:

• A tagged release of Zig or ZLS must be used with the same tagged release of Zig or ZLS
• A master/nightly build of ZLS requires master/nightly build of Zig

A master/nightly build of ZLS may be usable with older Zig versions (like the latest tagged release) but this is done as a best effort and may break at any time. If you rely on this behavior, your are destined to have incompatible Zig and ZLS versions at some point.

The ZLS install page should be used to query the compatible ZLS versions.