Towards better versioning policy

[Gaukas Wang]

As discussed before, to reduce the extra workload and confusion in maintaining uTLS across multiple different Go versions, uTLS is set to support the top 2 MOST RECENT Go (minor) versions. e.g., for April 02, 2024, the latest Go version is Go 1.22.1 so we will support Go 1.21 and Go 1.22. That is to say, once uTLS bump up the minimum version required to go 1.21, Go 1.20 and older version of Go will no longer be able to build and run programs built with uTLS as a dependency.

We also acknowledge and are deeply concerned about another issue mentioned in #249, that past updates to uTLS have broken backward compatibility for a few times for various reason, causing old code no longer compile with newer version of uTLS. While there are human errors in the maintainers of uTLS by mistakenly removing/renaming public interfaces, other uncontrollable factors such as crypto/tls making breaking changes to their function signature or crypto/tls exporting a type in a name existing in uTLS are more concerning.

Onward, here's a few possible versioning policies we can adopt, with pros and cons for each:

• Strict Versioning Policy: Whenever there is a minimum Go version requirement change or change to Type/Interface/Signature, we bump up the MAJOR VERSION (now v1) of uTLS.
  • Pros: There will not be a compatibility issue.
  • Cons: go mod's automated dependency update will not work at all.
• Moderate Versioning Policy: Do not bump up MAJOR VERSION for minimum Go version requirement changes. Do bump up MAJOR VERSION when Type/Interface/Signature changes or "could have changed".
  • Pros: At a certain degree we allow go mod continue to work.
  • Cons: It could be non-trivial to detect if there's an API breaking change if it is from upstream and got merged when we sync.
• Relaxed Versioning Policy: We keep uTLS in v1 and reserve v2 for a groundbreaking update, which may or may not occur in the near future.
  • Pros: it is always possible to use go mod and dependents of uTLS can be updated anytime.
  • Cons: when API is broken, direct dependents of uTLS which also imports other dependents of uTLS may fail to compile if the old (broken by new version) API of uTLS is used in the imported dependents.

[VeNoMouS]

Re: crypto/tls ..

Let's not forget that whole debate about switching to cloudflares branch of crypto/tls due to their work/changes on ECH etc

[Gaukas Wang]

Let's not forget that whole debate about switching to cloudflares branch of crypto/tls due to their work/changes on ECH etc

Only if cloudflare can stop rebasing their commits 😅

Unlike us, cloudflare rebase their changes/commits on top of latest main branch of golang/go (ir)regularly, which is pretty tricky to maintain since we are also making changes based on theirs.

[Simone Basso]

Thanks for opening this issue, @gaukas!

Regarding this:

Cons: go mod's automated dependency update will not work at all.

I assume you mean that go get -u -v ./... will stop updating, is that correct?

I don't know if it's helpful, but I have been recently using https://github.com/icholy/gomajor to check whether I need to upgrade to major versions of OONI dependencies.

[Gaukas Wang]

Hi @bassosimone, thanks for the reply. Yes, that's exactly what I meant.

While third-party tools (such as the one you mentioned, icholy/gomajor could be quite helpful in this case, it is obviously that automated procedures such as go get -u -v ./... or GitHub dependabot will be impacted. And we just cannot simply assume/suggest all importing parties should use any certain third-party tool.

For now I am leaning towards the last two options, with a strong preference in tagging a v2 in the very near future to first address all the existing forward compatibility problems once-and-for-all, which would at least buy us some time in figuring out a more proper long-term solution.