Thanks for pointing me to that discussion. As I suspected, there are lots of considerations I haven't thought through.
I like the idea of a key like 'metapackage or 'subpackage-of to explicitly encode the relationship between "foo"/"foo-lib"/"foo-doc"/"foo-test" package groups, which seem to be a prominent part how the Racket package system is used in practice. Without looking through the catalog, I don't know whether all platform-specific binary packages fall into a structure like that. I will give this some more thought. -Philip On Mon, Mar 26, 2018 at 11:08 AM, Jay McCarthy <jay.mccar...@gmail.com> wrote: > 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.
