Package details pages should provide more detail about badges

[savetheclocktower]

Have you checked for existing feature requests?

• Completed

Summary

Some packages are outdated or broken or archived and are indicated as such in the package “card” partial that is shown in package lists and on the package details page. But they're arguably a bit too subtle on the latter page.

For instance: suppose I visit the page for busy-signal. I may or may not notice the red pill-shaped “outdated” badge near the package's name, but it's less likely I'll realize that the badge itself links to a page that gives more information.

Ideally, that information would be shown in an info box near the top of the package README:

If this weren't possible, we could at least include as much information as is contained in the badge:

What benefits does this feature provide?

Sometimes badges carry important caveats (this package is outdated or broken) and sometimes they're almost ornamental (this package is made for Pulsar, so you should feel better about installing it!).

I recently mentioned to a user in passing that they should install linter-eslint-node if they want ESLint integration — forgetting that the last Atom version had some bugs and that the package's registry page doesn't make it obvious that you shouldn't click on the Install button on the page and should instead install by running a command in your terminal.

Any alternatives?

It's possible that we should also flesh out the metadata that's available from the API so that we can deliver explanatory text straight to the package's detail page instead of merely linking to it on GitHub.

Other examples:

No response

[confused-Techie]

@savetheclocktower This is a great feature request. Totally agree that this is a great start on including more information.

There's honestly more information I want included on this page, but being honest I do worry about how much time it'd take me to figure out the CSS side, when I'm hoping to get my CSS changes merged on the docs repo, since then I'd rather get these sites using the same styles,

But this is especially a great start

[savetheclocktower]

@savetheclocktower This is a great feature request. Totally agree that this is a great start on including more information.

There's honestly more information I want included on this page, but being honest I do worry about how much time it'd take me to figure out the CSS side, when I'm hoping to get my CSS changes merged on the docs repo, since then I'd rather get these sites using the same styles,

But this is especially a great start

Start from the backend: make whatever changes you'd want to make in order to support the display of extra explanatory badge-related text on a package's details page. I'll handle the CSS. We don't have to ship something perfect to start.

[confused-Techie]

I appreciate that, I'll start looking at what we could do to get badges improved

[confused-Techie]

So looking at this again, I think the real key component is we need to de-integrate the details of an administrative action on a package from the random markdown file that contains it.

What may be a better approach is creating a new table on the main database that contains listings of admin action IDs and package IDs.

I think what needs to happen is firstly:

1. We store admin actions as individual objects, no longer part of some giant markdown file in the backend repo.
2. Then we either link to that data in the badge field of a package, or the backend handles getting that data and adding it into the backend.

If we did that it'd solve a few problems:

• Obviously, we could now have much more data represented in the actual badge, up to all of the information that is available in the admin action itself, which is exactly what is being called for here.
• It'd also mean that publication of admin actions no longer requires waiting on a PR to be merged to the backend, since it'd be published at the same time as the badge itself is.
• Also as a side note, depending on implementation it even means we could make admin actions query-able if there was ever a need for that to happen.

So with the above idea, as long as there's nothing inherently flawed in it's design, I think that leaves us with the final big question: How do we store the new admin actions data?

• Do we create another table in the main db to store it? It does often include large bodies of text, but I don't necessarily see why that would be a problem, but we may want to double check if that could ever cause performance issues in postgres.
• We could alternatively store this data in Google Cloud Storage, we already do use that for some small bits of data, but the only issue there is that is paid for storage, so the more we use the more we pay.
• Lastly, we could serve these as JSON objects from one of our GitHub Pages domains, that does bring back the fact that there will be lag between the badge being added to the backend, and the badge data actually being published, which could be problematic.

With those options I think the one I like the most would be putting it all in a DB, but I'm not sure if that's the best method to store lots of text and if that has any performance penalties. But especially if it's already in the DB that means the backend would automatically collect it and add that information into the package's data, keeping it's 'service contract' identical to how it works right now, which is something we do want to seriously consider as the bundled settings package also uses badges, and we want to do our best to keep everything backwards compatible in case people are running old versions of Pulsar.

[savetheclocktower]

@confused-Techie, does it honestly need to be qualitatively different from how we're doing badges now?

I see that you've got a data column on packages; could we just add another description field to the badge objects that are being stored in that column?

I have no opinion on the record-keeping process you're using for administrative actions. As far as I'm concerned, that process could stay the same. I'm not even asking for the text of an administrative action to be represented on the package page itself — not exactly! The phrasing of the admin action could be whatever you like (the reasoning behind the decision, etc.) but the text on the package page should be entirely user-facing, with the goal of telling them what to do next. (This package is outdated. This other one is a fork; try installing it instead.)

[savetheclocktower]

Also, as a medium-term objective it'd be nice if there were some sort of UI (even a very basic one) for adding badges to packages from a web browser somewhere. I know that implies authentication and that complicates things, but I also don't think it's fair to give you a chore every time I think a package needs some guidance text on its repo page.

[confused-Techie]

I suppose that's a fair point. We could, technically, just write in more data than we do currently for the package and leave it at that.

I mean, really I guess that's not that big of a deal, and especially adding it as a new key means it'll be 100% backwards compatible. The answer could really be that simple if we wanted too. I may have gotten slightly carried away with the ideas, partially because it seems weird to have a db and stuff so much vital information into a JSONB object on it, but it does just work

[confused-Techie]

Also, totally agree we need a webUI to manage packages. I actually have some stuff from a prior attempt at that, so it might be worth a revisit.

There were some other details I wanted to add in there as well, to make it even more useful, so it would be good to get going

[savetheclocktower]

Eventually it could be a badges table with a one-to-many relationship with packages. Might be a bit tricky to migrate the data, but not much.

That said: on the scale of data we're talking about, I think the weird JSONB object will do nicely for a while. If we ever wanted to query against badges, maybe that's when we'd want to make it less ad-hoc.

[savetheclocktower]

So I'd ask for a description field on badges that can accept Markdown. It could use HTML instead, but I think it's easier to be consistent in the structure of the description if we do Markdown, and it saves us from having to write a bunch of <pre><code> and </code></pre>s.

[confused-Techie]

Yeah this seems like the best way. And like you said we can make it a bit more stable later on if we wanted to.

But that sounds good then, so we would:

• Need to add support for the description field in the frontend, and settings-view
• Add this new value to the badge spec, and begin using it, adding it to previous package's where possible.
• Ideally, create a webui for this data to be updated by the team.

Also having it support markdown is very good call to make our lives a whole lot easier.