We talked about this issue when the badges were added but could not come to an agreement about how to do it
https://github.com/tonyg/racket-pkg-website/issues/58 In particular, you can see the commit that Conor Finegan made to implement part of the idea that was rejected. Jay On Sun, Mar 25, 2018 at 5:49 PM, Philip McGrath <phi...@philipmcgrath.com> wrote: > 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 > <racket-users@googlegroups.com> 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. -- -=[ Jay McCarthy http://jeapostrophe.github.io ]=- -=[ Associate Professor PLT @ CS @ UMass Lowell ]=- -=[ Moses 1:33: And worlds without number have I created; ]=- -- 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.
