Epic - Community plugin registry

jmcook1186 commented 7 months ago

User story

As a user I want my plugins to be discoverable while also keeping control of the code in my own repository.

Rationale

To encoiurage decentralisation of the plugin ecosystem while also enabling usrs to browse plugins, we will create a plugin registry. This ticket covers the actual build and deployment of the new site.

Scope

[x] #617
[x] #614
[x] #661
[x] #735
[x] #684
[x] #685
[x] #634
[ ] #686
- [x] #797
- [x] #798
- [ ] #828

zanete commented 6 months ago

Need to set up a design call with @jawache @jmcook1186 @zanete

zanete commented 6 months ago

@jawache to kick off this feature, please put down your vision for the process and the registry platforms behaviour 🙏

jmcook1186 commented 6 months ago

I can butt in with some basic info to get the ball rolling.

I'm envisioning a simple webpage deployed at registry.greensoftware.foundation or plugins.greensoftware.foundation or similar.

Maybe we can use a more appealing term than "registry" - maybe "marketplace" or "bazaar" or "explorer"...?

The webpage should include links to either a Github repository or npm package for each plugin. The design of the page is not yet known, but I'd speculate that some thematic grouping of plugins would be a good idea.

Here are some examples from other projects:

JQuery plugins Terraform Gulpjs Wordpress

The webpage needs to be updateable by PR to a dedicated repository in the if namespace (github.com/Green-Software-Foundation/if-xxxx).

Discussions around the decision making process for accepting/rejecting PRs for listing plugins is happening here.

jawache commented 6 months ago

Thanks @jmcook1186 I was pretty blocked trying to think through this issue but going through your examples above has unblocked me!

Two things I've realized, (1) the registry I think we should eventually have will take some time to refine, get together (2) we should strike while the iron is hot, we've got people who've created plugins and we want them to have a place to put them now.

So what I think we should aim for is an MVP that's good enough for now, but we can evolve later on to be much more robust.

I like how Gulpjs does it, it's just a searchable list that surfaces some key details but when you click the link, it goes to the NPM (or GitHub I assume if there is no NPM) - that actually also puts some distance between us and the plugin, we're just a search engine for plugins, hosting pages related to each plugin on our website gives the impression we're giving it our stamp of approval but for some reason just being a search engine makes me feel more comfortable.

So a page of plugins, it's searchable, each is like a card. The page should have a big disclaimer at the top which we will define later. Header should have links to the IF and How to submit a plugin. The list of plugins can be a json file in the repo which someone needs to create a PR to add to, we review the PR ourselves.

What does the card show:

Name of the plugin
One sentence summary.
Tags?
npm link, repository link, website link
If it's an official GSF plugin it should be marked something special.
If it's possible to suck in some stats from NPM, then things like number of downloads, number of stars things like that (but make it clear it's stars on someone elses website, not stars we have given it)
Clicking on the card takes you to npm, or github or website as fallbacks.

@jmcook1186 we should have some guidance even in this initial version for what the readme/npm page contains. We should create a template which they should have to match. As a minimum

Inputs
Outputs (Part of me is thinking in the future version of this registry, we'd allow people to search through the inputs and outputs of plugins, that's the key bit of information you need to build a pipeline where multiple plugins connect together)
Global Config
Node Config With very strict rules for how those should be laid out on the page.
Summary
Description
Example Manifest File Usage
Evidence? (Why is it correct, citations, how have you verified that he numbers it outputs are correct?)

Q) @jmcook1186 do we assume that every plugin has to be on NPM at least, if we do then that simplifies a lot of things esp. since it means we can always suck in some stats like downloads

Q) @osamajandali , I'd rather not invest a lot of time/$ in the phase 1 version of this registry considering we'll be updating it soon to something better. So if we can leverage some off the shelf solutions (like docusaurus) and host at plugins.if.greensoftware.org that is best. Any suggestions?

jmcook1186 commented 6 months ago

Yes, I love the aesthetic of each plugin being a (expandable?) card. I like how the wordpress example in my previous comment is laid out.

The card could contain the plugin title (hyperlinked to its repository), 50 word description, npm/github tag and a badge (GSF logo for official plugins, badges indicating the thoroughness of the metadata provided with the plugin). You could hide the remaining information and expose it when the card is expanded on-click.

Do we want to have a strict requirement that the plugin is on npm? It's a substantially higher bar than Github. We can install models directly from Github from within IF and it's where msot people are comfortable. Especially as many of our builders might not be JS natives.

Templating the submission is a must in my opinion - we should make it very easy to provide the right information and make it very obvious when some information is missing. We can call on plugin owners to provide evidence of correct execution (tests and working manifests) at submission time.

I can draft something for review.

zanete commented 6 months ago

@jawache @jmcook1186 we've refined a design issue in #661 and look forward to @osamajandali first version in figma soon. 🙏

zanete commented 6 months ago

@pazbardanl here is the overall vision for the plugin registry epic

Green-Software-Foundation / if