Use Gleam version as a constraint in package resolution

[mine-tech-oficial]

As the title describes, allow package resolution to consider the gleam field in gleam.toml as a constraint check, so that when packages upgrade to a newer Gleam version, users of it aren't required to manually adjust its range

[giacomocavalieri]

Would this be a net positive? Wouldn't we want to encourage folks to always keep their gleam version up to date?

[mine-tech-oficial]

I would say that, if for some reason someone needs to support a specific version, they don't need to worry about bugs each time they update. An example (which is what, I suppose, quite some people stumbled on) was the (unofficial) Gleam Chess Tournament, as the code ran on container with Gleam v1.9.1.

[silby]

I would also have benefitted from this today. OpenBSD 7.7 has Gleam 1.9.1 in ports and OpenBSD ports/packages are only backported to the stable release in a somewhat ad hoc way/when there are security issues justifying the effort. I ran a package bump with Gleam 1.11.0 on my desktop but then had a compatibility issue with 1.9.1 on my server. I was able to tweak my manifest to fix it by constraining the package at issue.

[lpil]

@silby You must never edit the manifest. You should edit gleam.toml.

[silby]

Oh I see I was misleading. I induced a change in the manifest by editing gleam.toml. Clear communication eludes me this week.

[lpil]

Ah right! Thanks

[mtlynch]

This just bit me as well. I'm on NixOS, where the latest version of Gleam available is Gleam 1.10.0 even though the latest version is Gleam 1.11.0.

If I create a new project with gleam new, it pulls in a version of gleeunit that's incompatible with my version of Gleam:

$ gleam --version
gleam 1.10.0

$ gleam new --name myproject --skip-github .
Your Gleam project myproject has been successfully created.
The project can be compiled and tested by running these commands:

        gleam test
$ gleam run
  Resolving versions
Downloading packages
 Downloaded 2 packages in 0.01s
  Compiling gleam_stdlib
error: Incompatible Gleam version

The package `gleeunit` requires a Gleam version satisfying 1.11.0 <= v but you are using v1.10.0.

gleeunit 1.4.0 is correctly declaring its dependency on Gleam 1.11.0, so it would be helpful if gleam new considered that when choosing which version of gleeunit to pull in for a new project.

[manveru]

I was bit by the same issue, luckily NixOS/nixpkgs#407394 bumped Gleam to 1.11.0, but I think generally we should make use of the information that package maintainers provide to resolve versions properly.

[silby]

Herein I harvest and expand on a comment in closed #5008 into this open discussion instead, where it's more appropriate.

In brief: the gleam version lower bound constraint in gleam.toml should be applied to dependency resolution when constructing a manifest, such that every dependency in the manifest declares a lesser or equal lower bound to the lower bound of the current package.

Rationale

I take it as a given that it is good, not bad, for package repositories to package and distribute Gleam, as some in fact do. Projects have different approaches to release stability, ranging from rolling-release (e.g. Arch Linux, Void Linux, Homebrew) to medium-term stabilized releases cut from a single head (e.g. OpenBSD -release versions) to long-term branched and stabilized releases (Debian stable). The simplest way (and in certain cases only practical way) for many users to install Gleam will be through OS packages.

This ultimately leads to the phenomenon, well-known from Debian stable users, of users being stuck on out-of-date versions of things, to the periodic chagrin of upstreams who get bug reports that should be going to Debian package maintainers. In Gleam's case, Debian release engineering has posed an obstacle to packaging Gleam before it even gets particularly close, cf. #3160, but we can suppose that if anyone ever goes for it there will be Debian users getting old versions of Gleam when they apt install gleam.

OpenBSD releases, as discussed in #5008, are always fresher than Debian stable, but whatever Gleam version is built from the ports tree in the spring and fall will generally be the only one packaged for the release version outside of a security issue. OpenBSD also doesn't guarantee forward- or backward-compatibility for binaries you build on it, so my Gleam project hosted on my OpenBSD VPS pretty much has to be built there, using the packaged version of Gleam and the system toolchain and libc for native dependencies. I'm not incapable of building a newer version of the Gleam port for myself on a release version of OpenBSD but it's a yak I choose not to shave. The alternative I have is basically trial-and-error pinning of my dependencies, including transitive ones. My gleam.toml now contains lines like:

gleam_stdlib = "0.60.0"
exception = "2.0.0"
gleam_time = "< 1.3.0"

all of which I had to go inspect source history of the packages to get right.

Even users that use an up-to-date Gleam on their own machines, perhaps packaged by upstream, may have to build and deploy code on systems that are standardized on an older Gleam. Even a lag of a few working days in upgrading a shared build system from one Gleam minor version to the next can cause a bad developer experience, when, for example, a SemVer-safe version bump to the stdlib done by a bot causes a build failure.

What do others do?

Obviously in the case of Ruby and Python, unlike Gleam, there are support policies for the multiple annual releases of the interpreter, so the demand/use-case for this feature is more mature. Still, two examples:

uv

With a pyproject.toml containing:

requires-python = ">=3.10, <3.11"
dependencies = ["numpy"]

uv lock resolves to numpy 2.2.6. numpy 2.3.0 doesn't support Python 3.10.

bundler

With a gemfile containing:

ruby "~> 3.1"
gem "plissken"

bundle install resolves to plissken 3.0.0. plissken 4.0.0 doesn't support Ruby 3.1.

What's the impact of doing nothing?

I don't know much about your approach to evolving Gleam-the-language, gleam-the-compiler, or the stdlib. It's possible that after the stdlib hits 1.0 it'll become drastically less likely for old versions of Gleam 1.x to be unable to compile new code. But since you're explicitly not engineering for forward-compatibility (which is fine) I don't think you could easily make even a best-effort commitment here. Still, this might become less relevant soon. Without this feature though, in cases where the minimum Gleam version of dependencies advances within a major version, people in my situation have to laboriously pin package versions to avoid getting hosed by a gleam update.