While we're (sort of) on the subject of badges on pkgs.racket-lang.org: the "This package needs documentation" badge is mostly great, both as a producer and consumer of packages.
I've encountered at least two types of cases, though, where packages may intentionally and justifiably lack documentation (or at least not have it in a form that pkgs.racket-lang.org can recognize): - Packages that are split up into "foo"/"foo-lib"/"foo-doc"/"foo-test". The server doesn't know that "foo-doc" documents "foo-lib", so packages like "foo-lib" get the "needs documentation" badge. For example, "gui-lib" gets the badge. - Packages that just distribute platform-specific native binaries, like "ffmpeg-x86_64-win32". It's a bit more complicated in this case to generalize where the documentation is, and it is certainly at least arguable that there should be some sort of documentation of the existence and purpose of such packages, but it would probably be very silly to give each one its own "scribblings/ffmpeg-x86_64-win32.scrbl" as the package server expects. Giving these kinds of packages the "This package needs documentation" badge seems less than ideal for package consumers: I'm probably not the only one who avoids depending on undocumented packages. Most of the time, of course, it isn't too confusing given a moment's thought (assuming one knows the -lib/-doc/-test convention and/or the maintainer filled in the "description" field), though there do seem to be some native binary packages that are not obviously linked to their client package(s), but even a momentary stop-and-think impedes quickly scanning or programmatically filtering the search results. There's another downside for package maintainers, which is that these show up as "todos". While, again, maintainers probably don't have to think much about it when they actually review them, the existence of intentional/expected "todos" prevents maintainers from applying the simple rule that nonzero "todos" always means there's something they should go and fix. I think the most useful resolution would be to give package maintainers a way to specify that some package documents or is documented by some other package (or possibly some arbitrary URL—I would have reservations about that approach, but it seems worth considering whether it might be useful for the case of native binary packages). Other options I can imagine, like adding a way to just suppress the badge, seem less good in that they would weaken the badge system. This is a post and not a pull request because it seems like there are a lot of details that would need to be agreed upon, and I'm not sure I know the right answers or all of the non-obvious implications. (For example, should the documented package point to the documenting package, or vice versa, or should both packages have to "agree" on the relationship?) If consensus emerges, though, I would be happy to contribute some implementation effort! (Eventually …) -Philip On Sun, Mar 25, 2018 at 1:02 PM, 'John Clements' via Racket Users < firstname.lastname@example.org> wrote: > I’m fixing problems related to documentation on the libgit2 package, and > it appears there are a number of issues to fix, but the first one was that > the package was written with a main scribblings file called “manual.scrbl”. > It turns out this is a bad idea, and in fact this is mentioned in the raco > documentation, and there’s a helpful “conflicts” file that appears in the > “Most Recent Build Results.” (Unfortunately, I didn’t find this until I’d > already figured out this part of the problem.) My question is this; have we > given any thought to adding a conflict notification—either a badge or an > entry in the green box—to the front pkgs.racket-lang.org page? > > Apologies if there’s some good reason this isn’t already a thing. > > John > > > > -- > You received this message because you are subscribed to the Google Groups > "Racket Users" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to racket-users+unsubscr...@googlegroups.com. > For more options, visit https://groups.google.com/d/optout. > -- You received this message because you are subscribed to the Google Groups "Racket Users" group. To unsubscribe from this group and stop receiving emails from it, send an email to racket-users+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.