I would like to ask if there was some way to have a versioned version of Pursuit. It’s difficult for people to learn PureScript from any written material that refers to library functions that have changed.
In particular, my book, Functional Programming Made Easier, is written in PureScript 14. I originally wrote it in 13 and right before I was ready to publish, 14 came out and I had to change it to 14.
Now 15 is out and enough has changed to make learning PureScript using my book less than ideal.
If we hope to promote PureScript and have it adopted by more people, we should do all we can to not unnecessarily antiquate the learning materials available. My book is nearly 2000 pages and I cannot afford to rewrite the code every time a new compiler comes out.
I encourage readers to stick with 14 knowing that newer versions of the compiler will eventually come out. I also encourage them to use Pursuit throughout the coding exercises.
Not having a version of Pursuit for version 14 of the compiler is very difficult for new learners.
Another downside to not having Pursuit versioned is for experienced developers whose production code bases that are still on 14. When they want to look up a library function, many times they find that the function is deprecated or changed or is new in 15 and not available in 14. This is very frustrating.
It’s unrealistic to think that the whole world is going to rush ahead to adopt the next version of the compiler as soon as it’s released. Authors and those who maintain PureScript learning resources need time to move their materials to newer compiler versions.
I would be willing to help in any way I can (even though I know zero about Pursuit) to help make this possible. Or at least cheer on those who can make this a reality.
If this is a project worthy of anyone’s time, I’d like to suggest we at least create a version of Pursuit that coincides with version 14 and every version thereafter.
Hm I’m trying to understand what you want. Do you just want to restrict pursuit searches to show 0.14-compatible packages?
Pursuit certainly retains all the package versions, and users can manually select those and you can link to those specific versions. Of course it’s not always clear what package versions would be 0.14-compatible, that metadata is not currently available in pursuit or the registry. (Other than the rule of thumb of “probably one major version behind latest”, for core/contrib or other stable packages. Or looking at the required prelude version. The package upload date could also be used as a rough indicator, but it isn’t always accurate since documentation isn’t always uploaded in a timely fashion.)
Other than that I’m not sure what a versioned Pursuit would mean.
The 0.14–0.15 migration was a bit of an exception because it changed the FFI format (by popular request). Most other breaking changes have been much smaller, and I suspect they will generally be even smaller going forward. I can’t actually think of breaking changes for the compiler that we have pending atm? (Other than I selfishly want some kind of breaking change so we can move forward the SemigroupMap / Map deprecation cycle … I like my monoids, okay??)
Not having a version of Pursuit for version 14 of the compiler is very difficult for new learners.
The primary thing we have planned is to allow you to select a compiler version on Pursuit and only see results from packages known to work with that compiler version. For a package to be “known to work”, it means we were able to compile it with its dependencies with that compiler version. The data would then be stored in the package metadata (here’s the one for aff-bus).
To know this we must actually compile the packages. The new registry compiles packages when they are uploaded, but only with a single compiler version. When the registry server is up we hope to expand this so that many compiler versions are tried with each package & package set.
Would this solve your problem?
If this is a project worthy of anyone’s time, I’d like to suggest we at least create a version of Pursuit that coincides with version 14 and every version thereafter.
The biggest issue with Pursuit is that it is an old Haskell code base that, quite frankly, none of us infrastructure maintainers have much interest in working on. However, Starsuit (which lists only packages from the latest package set) has laid the groundwork for rewriting Pursuit in PureScript, at which point it’ll be easier to integrate it with the registry using the registry library and we’ll show it some love.
Unfortunately, none of this has been a priority yet, but it’s something I’d like to see happen in 2023.
Yeah that’s accurate. Starsuit is meant to be a “client-side Pursuit restricted to a single package set”, and it’s nothing more than some CI that:
installs in a Spago project all the packages to include in the search (the whole package set)
runs spago docs
hosts the resulting docs folder on GitHub pages.
I suspect this would be enough for your current needs? Take the latest package-set for 0.14, put your own Starsuit up on GitHub pages, and point the book users to that?
Aside: as Thomas mentioned above, once the Registry is launched, then we can:
run a Matrix Builder to compile every package version with every compiler and figure out what is compatible with which version
propagate this information to the Registry
port the useful bits of Pursuit to PureScript and make proper use of all this new information from the Registry.
I think we’re most of the way there: the docs-search project - which is what powers spago docs - is already implementing the search index and the search app, so we’re missing only the database side of things where we store all the docs for all the packages. We can even skip having an HTTP API, since the Registry CI can take care of generating the docs.
… I like my monoids, okay??)