To someone new to Racket - looking at docs.racket-lang.org - this is basically a "soup" of things that seems to be an unordered brain dump of everything Racket related.
I may have missed the memo buried on that website (can you blame me?) but if you do not know the history of all these projects (including Racket itself) - what qualifies a project to end up on that site? Are there indicators of how mature a particular project is? For example, is typed racket production quality? What about Rebellion? What is just an attempt and what can be used in the real world? Time to come up with some classification system?
Regarding the question in your title as to what is official, my take is that everything under Racket Language and Core Libraries as 'official' and that's it. The rest I consider as extras, with all the caveats that entails.
As to how the non-core stuff ends up on that page, I have no idea.
If I remember correctly, the topic also came up at RacketCon. I think it was @jeapostrophe who categorized packages into "rings", see for example typed-racket. "Ring 0" means the package is an official/core one. I don't remember the criteria for other rings. I see that all my packages are categorized as "ring 1", so I'm not even sure whether there are rings beyond that.
We also had a discussion about this topic at the last Racket online meeting, with the outcome that it's unclear to a visitor of the package server what "ring" means. Probably "Ring" should be a link to an explanation about what "ring" means. Can we find a term which is less abstract than "ring"?
If there are only two rings, we could replace "Ring: 0" with "Official package: yes" and "Ring: 1" with "Official pacakage: no", or even better, for ring 0 packages just put a sentence after the description that the package is an official package.
My packages showed up there automatically after the release, so I assume the list includes the Scribble documentation of every Racket package on the package server. Conversely, this means that if a package has only a README file, but no Scribble documentation, it won't show up in the documentation list.
Racket's documentation workflow does stand out as a bit surprising at first, especially compared to most other language ecosystems. Anyone can publish a Racket package to the package server. If it has documentation, it should appear in the list at https://docs.racket-lang.org/, which is why it's quite a long list.
After being around the Racket community for a bit, I find I quite like this ability for anyone to create something that appears on the main documentation site.
However, it does need a bit more "curation" or something to make the situation more obvious, especially for newcomers. Perhaps the docs index page (https://docs.racket-lang.org/) could be annotated or grouped in some way to highlight packages in the main distribution, which is likely the main indicator of "official" at the moment. Beyond that, it gets a bit fuzzier.
I guess what I (personally) would like to see is a) is the package production ready (according to author(s)), b) is it actually used in a product/production by someone else (and who), c) last time the code was updated (is it actively maintained?) and d) are there unit tests.... so on and so on. Basically, level of maturity of a particular code base.
I think at this point Racket has "rack(et)ed up" quite a few options/packages and it may be becoming confusing for people entering the game to figure out what's what and what to spend their time on. I would volunteer to do the work if any decisions are made.
Would it be helpful for the documentation pages themselves to show the provenance -- the package name, and its ring?
I think so... but I'm not sure where, or how.
If a package has a defmodule, then the docs show a package: foo link. You're one click away from the ring and other metadata.
But only if you know to click it.
And only for that defmodule -- if you end up on that doc page with it scrolled off-screen (or on a different page for a package with multi-page docs!), you won't see it.
And doc-only packages might not even have a defmodule, and therefore a package link, at all.
So TL;DR especially if you land somewhere after a doc search, it likely won't be obvious what's the ring (much less package).
So it seems like it would be useful to make this more easily and directly discoverable.
But I'm not sure where/how.
Should each ring have its own color, and every doc page's left nav element use that background color -- plus get some new, clickable "package" element similar to defmodule?
I'm not sure that's quite right, but maybe someone has a better idea for something roughly like this?
I am considering Racket for a work project. I am a dev lead with quite a bit of freedom in deciding what to use on projects. It would really help me if I knew whether a particular package is production ready and if it is actively maintained. My discussion here comes from a bit of a selfish spot
I should also say that I come from a Scala background (prior to that C, Python and myriad others). In Scala it used to be the case (still is?) that the library ecosystem is a bit of a wild west but even then contenders for tasks kind of crystallized themselves out. I used to remember a lot of frustration in the early days of the ecosystem with spending days trying to figure out what is someone's throwaway experiment and what is a community supported/used proper production ready and maintained library. I feel Racket is in that spot now?
Note that the documentation page includes the rendered doc for every registered package submitted by any user to the catalog. You'd need to check the individual package.
The packages placed under the unstable collection are generally experimental and non-production ready.
The packages tagged main distribution are those officially distributed together with the core Racket libraries. They are pretty stable and mature, but for historical reasons also includes teaching languages, e.g. plai, deinprogramm and eopl.
"I am considering Racket for a work project. ... It would really help me if I knew whether a particular package is production ready and if it is actively maintained.”
Some basic background:
The “main distribution” represents the essence of Racket from the perspective of the core team.
It is more than a language but an ecosystem for easily getting started with teaching beginners, the core goal some 25+ years ago.
A project may need only portions of this bundle, but the good news is that 99%+ of this bundle is maintained properly.
If you install just the main distribution and look at the locally rendered docs, you get the idea of just “main”. You can then add the package you’d like.
There is a minimal Racket package, which is essentially just the language. You would then need to install additional packages to get the “batteries” going, many of them from the main distribution.
Some specific suggestion:
A large Racket project for a major US gvt agency used the following strategy:
(a) install the trusted main distribution
(b) create a package catalog for truly trusted packages
(c) work on that basis so that no untrusted code sneaks into the product.
If you want to experiment, start with (a) and add packages from the on-line catalog as needed. Just run raco pkg install for the relevant package. The local docs will be updated (like the global one).
Once you migrate to a product (“harden” your code base), consider the last two points (b, c) because they are important if you’re product is security sensitive in any way. Others have mimicked this strategy in some ways or others and can help with the catalog part. Ask on slack or this forum.
I guess I was hoping that the work of what is production ready vs someone's afternoon experiment would have already been done for me ;). As it is, adding packages and figuring our what's worth keeping and what isn't, means I have to do the work ;).
I think one issue here is how one defines "production ready". I wrote and use struct-plus-plus extensively in my code. I'm aware of one other person who has used it, although I don't know how much or for what. Is this module 'production ready'?
Likewise, I am of the opinion that "when is the last time it was updated" is the wrong question. IMO, a module should cover its core use case and have tests and documentation. Once that's done, it should only be modified (A) for (bug | security | documentation) fixes or (B) when someone comes up with a genuinely new and useful feature. It's a bad idea to continuously twiddle the code in trivial ways simply to make it look more appealing to people who are using "has this been modified multiple times over the last N weeks" as a metric.
