Suggestion: Include compiler ranges in package metadata

[thomashoneyman]

A PureScript package normally is compatible with some, but not all, compiler versions. I suggest that we allow package authors to specify this information in their package manifest the same way that dependencies are specified (as described in #43). In other words, a purs.json file would include:

{ "name": "my-package"
, "version": "1.2.3"
, "compiler": ">=12.0.0 <14.0.0"
}

Field names could be purs, purs-version, compiler, compiler-version, or something like that.

Why?

A manifest including supported compiler versions opens up a few new possibilities:

• We can verify that a package compiles when added to the registry (or package set) by ensuring it compiles with a sample of compiler versions in the specified range (at least 1 per major version specified, perhaps).
• We can show what compiler versions a package supports in the Pursuit documentation.
• We can add a filter to Pursuit that allows you to look at packages only associated with particular compiler versions. Folks regularly ask to see just 0.14-compatible packages, but it would also be nice to be able to go "back in time" when working on an old project and see only 0.12-compatible packages (for example).

[f-f]

I think we considered it in the past - the big issue with allowing users to specify compatibility ranges is that they are often incorrect in two ways:

1. overly restrictive bounds: a package version might be compatible with a compiler version but cannot be used because the bound prevents it
2. overly lax bounds: the package author specifies a bound that includes future versions of the compiler that might end up breaking it - in this way users are allowed to use the package but it would break their build.

To sum up: we wouldn't be able to trust such bounds, which might be worse than having them in the first place!

I think a more useful solution for this issue is something like the Hackage Matrix Builder, where all the packages that are uploaded to Hackage are built with various versions of the compiler to figure out the compatible versions (here's e.g. the build matrix for the purescript package).
We could set up something similar, and store all this info in the Metadata file for every package, here in this repo.

[thomashoneyman]

I agree that compatibility ranges are likely to be incorrect for the reasons you've specified, and I also think they're still useful to include somewhere that tools like Pursuit would be able to access them. So long as it's possible for Pursuit to access the Metadata information then it seems sensible to me that the information lives there.

I agree that something like the Hackage Matrix Builder is a good way to determine actual compatibility bounds for a package upon publication. Would a process like this make sense?

Package Update

When a package is added or updated, we test it across compiler versions:

1. We attempt to compile the package with every compiler version we choose to support (everything from 0.11 onward?)
2. For each major version that compiles, we switch to minor versions and compile with those.
3. For each minor version that compiles, we switch to patch versions and compile with those.
4. The resulting list of successful compilations is stored in the package metadata as an array of versions, ie. [ "0.11.0", "0.11.1" ]

Compiler Update

When a new compiler version is released, we walk through all packages and check if they compile with the new version. (We could narrow this by only choosing packages that already compiled with at least one version in the compiler series, ie. when 0.14.3 comes out we only re-check packages that compiled with at least 0.14.0, 0.14.1, or 0.14.2).

1. We add support for the new compiler version by making the compiler usable in our pipeline
2. We produce a list of all packages that should be re-checked
3. One-by-one we compile the packages, and add the compiler version to their supported versions in their metadata files if the compilation succeeds, and do nothing otherwise.

[thomashoneyman]

I've updated the name of this issue to reflect storing this information in the package metadata instead of in the purs.json file.

[natefaubion]

For each major version that compiles, we switch to minor versions and compile with those.

This assumes that a library which compiles on something like 0.14.4 will also compile on 0.14.0, which isn't always the case. For example, nameless instances were introduced in a "patch" release, though since it's still 0.x versioning, it's dubious to call it a patch release.

[thomashoneyman]

This assumes that a library which compiles on something like 0.14.4 will also compile on 0.14.0, which isn't always the case.

Alternately, we could compile with all compiler versions from a certain start version up to now; it’s a lot of compilation, but over not an enormous number of packages and so perhaps it’s ok.

[thomashoneyman]

I'd like to propose a specific solution for the build matrix. This assumes we have access to all compilers from the earliest library releases that have been registered (say, purs-0.6.0 or something).

Package Build Matrix Process

If we're doing this in bulk, then first topologically sort all packages by their dependencies such that no package is processed until its dependencies have been processed, then do the rest of this one-by-one.

Try to compile the package with all compilers according to the following rules.:

• No dependencies: attempt compilation with every compiler version, recording the first and last versions that work in a continuous range. For example: if slug@1.0.0 works with purs-0.13.0 and stops working with purs-0.14.0 then its range is >=0.13.0 <0.14.0.
• Has dependencies: solve the dependencies, then take the intersection of compiler ranges supported by each dependency. This is the set of compilers that will possibly work to build the package with its dependencies. (See Issues below for a reason why this may not be good enough, and a different approach we could take.) Then, try every compiler in that range, producing a range of compilers that worked.

Then, write the range to the compiler field in the package metadata.

New Compiler Added

When a new compiler version is added to the build matrix, all packages that could have admitted that version should be retried.

For example, if slug@3.0.0 worked with compilers >=0.15.0 and the latest compiler was 0.15.8, then we'd produce the range >=0.15.0 <0.15.9. Then, 0.15.9 comes out. We should retry all packages that had the upper bound <0.15.9 and, if they work, update their bounds — for example, slug@3.0.0 would become >=0.15.0 <0.15.10.

In the case a new major compiler version comes out we should do the same thing. We would retry all packages with the upper bound <0.15.9 using the 0.16.0 compiler. If slug@3.0.0 worked then it would become >=0.15.0 <0.16.1.

If the package fails with the new compiler then its bounds are unchanged.

Issues

1. Overly-restrictive bounds
What happens when a package like convertible-options is usable with a dependency like prelude: >=3.0.0 <5.0.0, where prelude@3.0.0 supports compilers >=0.13.0 <0.14.0 and prelude@4.0.0 supports compilers >=0.14.0 <0.15.0. Technically, depending on how you solved the dependencies, convertible-options is compatible with compilers >=0.13.0 <0.15.0, but will probably end up being listed as compatible with just >=0.14.0 <0.15.0.

Is it reasonable for a solver to take a compiler version into account, too, so that when solving convertible-options with compiler 0.13.0 it chooses prelude@3.0.0 and when solving with compiler 0.14.0 it chooses prelude@4.0.0? Is this a pie-in-the-sky dream, or would it actually make the solver work a bit better by trimming out paths?

2. Delayed metadata updates
This requires that, when we update the PureScript compiler and make a new release, we also need to update the build matrix at the same time so bounds can be retried. Otherwise, packages will have stale, overly-restrictive compiler bounds until the build matrix is updated and re-run for all eligible packages.

[MonoidMusician]

Is it reasonable for a solver to take a compiler version into account, too, so that when solving convertible-options with compiler 0.13.0 it chooses prelude@3.0.0 and when solving with compiler 0.14.0 it chooses prelude@4.0.0? Is this a pie-in-the-sky dream, or would it actually make the solver work a bit better by trimming out paths?

We can implement it as a fake package dependency that represents the compiler version bounds. I don't think think there'd any additional benefit to special casing it in the solver, since a fake dep would be used to prune possibilities the same, and this would mean we get to see it in the errors for free.