the argument against putting todo warnings on the public pkgs page

[mbutterick]

The todos have no appreciation of context. For instance, the docs for a certain package might not be in that package. In which case, there isn’t any way for a developer to fix the warning. For instance the docs for beautiful-racket are in the br package. Other packages may have no documentation intentionally. For instance, beautiful-racket-demo. Again, no fix.

More vitally, the todo warnings suggest to Racket users at large — especially new users — that the package library is full of incomplete, broken software. In general, that’s not true.*

[* Of course, some packages are incomplete or broken. And we could agree that it would be nice to have some kind of internal rating so developers could communicate whether relying on such-and-such package is wise. IIRC this was the idea behind the “ring” rating, though it seems to have faded out. Also, maybe tags suffice, but AFAIK there is no consistent vocabulary.]

There seems to be a common-sense middle ground, which is to only show the todo warnings when a developer is logged in, for packages that belong to that developer.

[jeapostrophe]

1. We ( @cfinegan and I ) are working on improving this, with for instance, the 'implies field. We can also add a tag like intentionally-without-docs for the situation you mention.

2. The todos don't show any information that isn't already there. The packages without docs previously had no links to docs. The packages without descriptions or tags, used to have blank areas. We're just turning 'nbsp into "No description" and some highlighting. I agree that it draws attention. FWIW, I disagree with you and think that the package library IS full of incomplete and broken software. Almost 40% of the main page's todos are about packages that fail to build or have failing tests.

3. The goal is to encourage users who want to help to identify things that they can do. Given that anyone can add tags, for instance, it is useful to do that.

[mbutterick]

In the past, you’ve argued that issues relating to package versioning are social, not technical. I agree, and moreover, I think that principle applies to the package system more broadly.

🐩 🐩 🐩

The todos don't show any information that isn't already there

They do impose a judgment that wasn’t there before: “this package needs …”

I disagree with you and think that the package library IS full of incomplete and broken software. Almost 40% of the main page's todos are about packages that fail to build or have failing tests

But this notion of “incomplete and broken” is a judgment inferred from an automated check. It is not based on the developer’s view of the software.

This creates a problem of false negatives. For instance, your apse package fails to build. But suppose you don’t intend for it to be compatible with the current version of Racket. If so, we can’t really say it’s “broken”.

🐩 🐩 🐩

The broader question seems to be what kind of standard of quality should be communicated / enforced by the package server, and whether this can be done effectively by automated checks.

The problem is that the package server serves two audiences with different needs:

• As a developer, I want the threshold to be as low as possible. The package server is a housekeeping convenience. It should impose minimal requirements. And no judgments, because the package server does not and cannot know my intentions. I want to be able to put up packages for any reason, in any state of completion.

• As a user, I want standards to be higher. I want to discover packages by understanding which are good, stable, reliable, maintained, used by others, etc.

But here too, automated checks fall short, because we have a problem of false positives. For instance, my css-tools package has docs and no build warnings. So according to the package server, it’s a good citizen of Racketland. But as the developer, I’d tell you it’s a piece of junk that I don’t want anyone to use.

🐩 🐩 🐩

IMHO the UI at pkgs.racket-lang.org should be minimalist and developer-oriented.

User discovery of packages would be better handled by improving the front page of docs.racket-lang.org, because that’s where all the best — meaning, developer-created, not machine-created — information about the packages actually lives.

[SuzanneSoy]

Maybe we can display the TODOs only for logged in users? That is, enable the feature for pkgd.racket-lang.org, but avoid displaying it on pkgs.racket-lang.org.

I agree that showing the endless list of TODOs to newcomers risks turning them away.

Some of these warnings cannot be "fixed" right now, e.g. the docs for my phc-adt package are in phc-adt-doc. I applied the new convention to link the two packages by tagging the -doc with the name of the "main" package, but the system does not know how to handle this yet (although I guess we might have this working very quickly). Also, only the package owners can add tags (see #44), unless something changed recently, so we cannot count on the community to fix this until #44 is implemented in some way or another. Until there is a way to dismiss the warnings in the proper way (indicating packages as related, or via the intentionally-without-docs tag mentioned by @jeapostrophe), i'd say it makes sense to keep the feature for logged-in users to give an incentive for curating their own packages, and disable it to not tarnish the public image of Racket's ecosystem.

[jackfirth]

Perhaps more radically, the package server could avoid showing packages with todos on the main page? Or at least put them lower on the list of packages than packages without any todos.

Maybe it's time to revisit the default ordering of packages. I'm a fan of ordering them by "most clients" - packages that are frequently used by other packages should appear towards the top, since they're more likely to be generally useful.

[tonyg]

I like the idea of "most clients". It avoids the privacy issues of "most installs" stats collection, while also being a reasonably plausibly useful metric.

Perhaps we could revisit the front page entirely. I've filed #53 to avoid hijacking discussion here.

[jeapostrophe]

Sorry for the long delay in getting back to the thread.

A big take-away for me is that Matthew & I agree on the idea that pkgs. is for developers and docs. is for users. Ideally for me, users discover packages by searching the docs or browsing the table of contents, rather than going out and "looking for a package". I like the idea that Racket feels like one big cohesive thing.

I really value "This package ..." over 'nbsp, because I want to draw attention to what is not there as far as what can be automatically done. I consider it a bike shed whether it says "This package has no tags" or "This package needs tags." I will happily change it to whatever text ya'll think is best.

[mbutterick]

Ideally for me, users discover packages by searching the docs or browsing the table of contents

docs.racket-lang.org has some obvious avenues for improvement. For instance, applying categories more consistently (most packages show up as “Miscellaneous Libraries”), and some kind of one-line description (most of the titles are not self-explanatory).

But I’m still confused about where, as a matter of Racket policy, package metadata wants to be stored. Right now we seem to have two disjoint piles:

1. tags (that show up only on pkgs.racket-lang.org) and

2. categories (and perhaps, in the future, other "info.rkt" fields) that show up only on docs.racket-lang.org.

IOW, is "info.rkt" meant to be the SSOT for a package? If so, then why have other package metadata live elsewhere? For instance, I could imagine tags becoming a field in "info.rkt" that the pkgs system looks up, rather than being information natively held by pkgs.

[jeapostrophe]

We talked about this a lot at our meeting in Oxford and I think we have something good to present to the community shortly. Sorry for the delay, but this seemed important.

[greghendershott]

Opinions:

Early on it was good/necessary for the package catalog to prioritize package authors' needs, feelings, and convenience. After all, we needed more packages.

I think maybe now the emphasis should shift more toward package users -- optimize more for quality, discoverability, provenance, dependability?

---

Maybe related: It's awesome when people want to share something they've done in Racket. Even if they're unwilling or unable to support it as a library that other people can depend on. We want to encourage that. Today people might feel like the package catalog is the only good "showcase". If we had some other "showcase" outlet -- e.g. some reddit-like thing where people link to their repo, and people can comment or up-vote -- it could allow the package catalog to focus on packages people can depend on.

---

To be clear, I'm not making any value-judgment here! Sharing something cool is good; people can learn from the source, be inspired, etc. Providing a library others can depend on, is also good. One isn't better. They're just different kinds of contributions.

The only potential problem is when both kinds are mixed into a big grab bag and it's hard to tell which is intended.

Meanwhile, so long as we're using the one big grab bag, I think signals like "needs docs", "broken deps", "failing tests" are helpful. If the language feels pejorative let's fix that, but not remove the signals completely?