Build Plug-in Registry - Githubissues

zanete commented 2 months ago

Why: Sub of #633 What: Implement the Plugin Registry website

Scope of work:

[x] Implement the Plugin Registry design from #661
[x] Update the button text at the top to be "How to submit a plugin" with link https://grnsft.org/if/how-to-submit-plugin
[x] Update the disclaimer in the footer

PLEASE BE ADVISED THAT IF YOU RUN CODE INCLUDED IN THESE PLUGINS OR USE INFORMATION GENERATED BY THESE PLUGINS, INCLUDING MAKING ANY DECISIONS BASED UPON THE INFORMATION, YOU DO SO AT YOUR OWN RISK. GREEN SOFTWARE FOUNDATION MAKES NO REPRESENTATION, GUARANTEE OR WARRANTY, EXPRESS OR IMPLIED, STATUTORY OR OTHERWISE, INCLUDING MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE NOR ANY WARRANTIES ARISING FROM COURSE OF PERFORMANCE, COURSE OF DEALING OR USAGE IN TRADE.

[x] Implement process to read data from Notion (https://www.notion.so/grnsft/f1fa58830db5470c887458abece48862?v=4a5401f951384b48b5f8a1228f2853f1)
[x] Update data for Launch from #685
[x] Implement Tag behaviour - on click, populate search with the tag as query and fire it
[x] Implement default order to be alphabetical by name
[x] Implement "build site" to manually rebuild after data change
[x] using the "Badge" column - if there is a value in the badge colunn, display "{badge column text} Plugin" as the badge
[x] Filter out plugins that are not approved (only show plugins that have TRUE in the "approved?" column
[x] Update the meta title and meta description as per the current title and description
[x] Deploy for review and feedback
[x] Incorporate feedback
[x] Deploy to https://explorer.if.greensoftware.foundation/
[x] Remove NPM link if there is no value
[x] update the Plugin title to be a link that takes you to npm and if that doesn't exist then to the GitHub.
[x] put the disclaimer above the footer links

zanete commented 2 months ago

@jawache @jmcook1186 do you have any suggestions / vision on the behaviour of Tags - are they clickable? if so, does it filter the plugins by that tag? Given the tags are submitted by the public via PRs, is there a limit to the tags they can submit? we also foresee inconsistencies etc, would there be a finite list that we support and maintain?

jmcook1186 commented 2 months ago

i definitely think we should support a finite set of predefined tags. I don't have a list of what those tags should be yet.

jawache commented 2 months ago

My suggestion right now is to make the tags something indexed at least, so if you search for a term and it's in a tag for a plugin, then that's a match.

I'm less bothered about making tags clickable for this MVP we'll have a couple of dozen plugins for now, if it doesn't add much time I'm not against the idea but if it's multiple days it's not that important imo.

@jmcook1186 agreed we should have some suggested tag names in the docs but also allow flexibility for them to tag as they like, we can't really guess the universe of useful tags at the moment.

zanete commented 2 months ago

Thanks @jawache and @jmcook1186 , I would suggest to leave it free for the MVP and then if we start getting stuff that means same thing but described by many different tags such as ai, artificial-intelligence, ml, llm etc, we can tidy up and implement a process with docs and suggestions.

@osamajandali do you have a comment for how much effort is extra if tags

are indexed and searchable
indexed + clickable to prefil search

osamajandali commented 2 months ago

Website is ready and I'm currently waiting for the data.

Tags are indexed, and users can filter by them, so we are in good shape now. There are a few tweaks remaining that need to happen after the data is in.

Do we want people to filter with multiple tags or just one tag at a time? If we need multiple tags, we should list all tags in the aside section so people can easily know what filters being applied.

zanete commented 2 months ago

For now, we can just have one tag filtering at a time due to the low number of plugins at launch.

jmcook1186 commented 2 months ago

Hi @osamajandali @zanete

I think the json data for each card could be as simple as this (I used a real plugin I made as an example):

{
    "name": "carbon-intensity-plugin",
    "github": "https://github.com/jmcook1186/carbon-intensity-plugin",
    "npm": "https://www.npmjs.com/package/carbon-intensity-plugin",
    "description": "Retrieve carbon intensity data from UK National Grid API",
    "author": "Joseph Cook, Green Software Foundation",
    "docs": "https://github.com/jmcook1186/carbon-intensity-plugin"   
}

jawache commented 2 months ago

Hey @osamajandali when you click on the card does it take you to one place right (npm or github if no npm or website if no github - I believe that was the functionality from the Gulp version)?

Or is clicking on different parts of the card going to take people to different places?

@jmcook1186 we also need the tags and I think some flag to indicate it's an official plugin (one of our's) maybe a badge for hackathon winner?

So something like this?

{
    "name": "carbon-intensity-plugin",
    "github": "https://github.com/jmcook1186/carbon-intensity-plugin",
    "npm": "https://www.npmjs.com/package/carbon-intensity-plugin",
    "description": "Retrieve carbon intensity data from UK National Grid API",
    "author": "Joseph Cook, Green Software Foundation",
    "docs": "https://github.com/jmcook1186/carbon-intensity-plugin",
    "tags": xxxxx
    "badge": "official" # or "hackathon"
}

jawache commented 2 months ago

Oh and should we also insist they have their email address in author, something they are willing to share publicly, we may need to contact them in the future?

jmcook1186 commented 2 months ago

ok - do we really want to support an official tag though - won't our "official" plugins really be builtins and therefore not listed on the registry?

I saw badges less for affiliation and more for achievements, like "100% test coverage", "great docs", "literature support", "hackathon winner" or similar (and that we would implement those later).

We can request an email I suppose - comes with some doxxing risks that not everyone will be comfortable with. Make it optional?

jawache commented 2 months ago

@jmcook1186 so I think we should list all our plugins here, doesn't really matter if they are builtins or not. Would be confusing to ask people to look in two places for the total list of things you can put in plugins. One stop shop to find the right plugin for your manifest.

For badges, the UI just supports one badge per card (I assumed at least), we can maybe have an editors pick badge then to recognize the plugins that have gone the extra mile with good testing, docs etc...

I think it's ok to insist on an email address, they can create a special one just for us or something from proton mail? Just some way we can contact them if there is a problem with their plugin, you can't DM people with just GitHub username :/ or at least list something where there is a way for us to DM them, twitter/linkedin/email?

jmcook1186 commented 2 months ago

ok fair enough!

osamajandali commented 2 months ago

Thank you, @jmcook1186, for the JSON format.

@jawache, the entire card will not be clickable due to the nested links, allowing each part to be clickable as necessary.

Regarding the email section, should it be included in the same JSON or perhaps in a separate file, like an .md file?

jmcook1186 commented 2 months ago

@osamajandali I'm going to try to get an excel file to you later today with a set of plugins ready for launch day - we'll probably have to iterate on it a few times as we are in the process of migrating some of our plugins between repos.

osamajandali commented 2 months ago

That would be cool, it's is always better to have some data from the beginning so that I can eliminate any possible bugs. Thank you @jmcook1186 !

jmcook1186 commented 2 months ago

@osamajandali I'll keep working on this during the day but here is a sheet listing our plugins to get you started https://docs.google.com/spreadsheets/d/1RXAAJxKqKoIaSr1O13eGR33utjW2PSpSfP2ZTqrX4nE/edit#gid=0

jmcook1186 commented 2 months ago

Hi @osamajandali @zanete @jawache

Can we change the name of the website from "plugin registry" to "IF Explorer"?

Two main reasons: one is that the registry sounds too dry and not fun - explorer is a bit more inviting. "Register" is also a term that implies more process than we are really going to provide, as for a registry there is a registration process.

Second, more important, is that later we will probably want to share things other than plugins (e.g. manifests, pipelines), so IF explorer is ambiguous enough to encompass those things too.

jmcook1186 commented 2 months ago

@jawache @osamajandali @zanete

After chatting with Asim, we decided to make the plugin submission a NoteForm that populates a Notion database.

@osamajandali it would be great if we could pull data directly from the database into cards on the website, but failing that, we should use the database in notion as the source of truth and manually create the json in the website repo.

I already made the form (https://noteforms.com/forms/if-explorer-plugins-njkhk5) and the database (https://www.notion.so/grnsft/f1fa58830db5470c887458abece48862?v=4a5401f951384b48b5f8a1228f2853f1)

We should also embed the form on the website

zanete commented 1 month ago

@jmcook1186 that looks great and i'm sure it can be done from Notion directly, thanks! Should I go ahead and add a property that will act as the flag on whether it. can be shown on the site? Did you want it to hold multiple values and represent some sort of status? Might actually be easier if you add it yourself and let us know what value to use.

With regards to embedding it on the website, that would require an additional page and a lot more context around it that you have documented and made available elsewhere. Are we sure we want to duplicate all this? will be more difficult to maintain. cc @jawache

osamajandali commented 1 month ago

Unfortunately, I don't have access to the links you shared, @jmcook1186, so I'm unable to proceed. I believe I need a GSF email to ensure I always have access to shared links without needing to request access. Is this possible?

osamajandali commented 1 month ago

Incase you want to see the website here you are: https://if-plugin-website.vercel.app/

jmcook1186 commented 1 month ago

Hi @zanete @jawache we need to unblock @osamajandali (see messages above) I've given guest access to the DB for now, but tagging you both in case you want to implement a different solution. @osamajandali you should be able to access the db now.

jmcook1186 commented 1 month ago

btw @osamajandali the website looks great!

One thing we need to remember is to add a DYOR style disclaimer somewhere. @jawache will need to sign off the copy and we'll need to decide an appropriate position for it on the page.

Anticipate something like:

"The Impact Framework team take no responsibility for the quality or security of the plugins listed on this page. We check that the necessary information is provided with a plugin submission at the time the submission request is made but we do not check the plugin code or verify its correct execution. You should carefully audit any plugins you intend to install."

osamajandali commented 1 month ago

@jmcook1186 Should this disclaimer be super visible or could I add it to the footer?

Now the website has the data from the spreadsheet.

One thing I notice is fetching the stats data for each plugin from both npm and github will cause blocking so I think we need to have like a cron job that fetches every x amount for time and update json.

jmcook1186 commented 1 month ago

@osamajandali It should pull from the Notion DB not the google sheet - and we'd like to filter based on the approved column (only render a card for the row if the check box is checked).

I think the disclaimer should be visible, but let's get @jawache to confirm - if it's ok in footer then great.

Cron job seems like a reasonable solution for github and npm stats.

zanete commented 1 month ago

FYI @jmcook1186 @jawache Ashara will add accounts@ to enable access (#735 )

zanete commented 1 month ago

@jmcook1186 can you share the link to docs on How to submit a plugin and where people can find the form currently? We need that for the button at the top And I'm still unclear on what the resolution is regarding embedding the submission form on this website. See my concern here cc @jawache

jmcook1186 commented 1 month ago

@zanete

Here's the tutorial page https://if.greensoftware.foundation/developers/how-to-build-plugins

I think the webpage could just have a clear link (SUBMIT YOUR PLUGIN) that links to the form, rather than an embed, if necessary.

zanete commented 1 month ago

Notion integration is ongoing as it's not as straight forward as expected
Decided to implement a manual step to "build side" after data changes in the notion db
@zanete to make a short link for "how to submit a plugin" as soon as it's live

zanete commented 1 month ago

@manushak can you share the approach you used in your integrations to automate the rebuild of the site upon data change in notion 🙏

manushak commented 1 month ago

To integrate the Notion database into the website, first, we need to create a Notion built-in integration. This has been done in the Notion <> Google Group integration. To automatically fetch data from the database, we can set up a CI/CD job to update every, let's say, 24 hours, which I have already done.

@osamajandali, we can have a call, and I'll guide you step by step

zanete commented 1 month ago

thanks so much @manushak - for @osamajandali, please only follow this if it is easier than the solution we agreed, as the goal is still to create the simplest solution to implement regardless of user experience.

jmcook1186 commented 1 month ago

@osamajandali @zanete @jawache Here's the disclaimer for the landing page

PLEASE BE ADVISED THAT IF YOU RUN CODE INCLUDED IN THESE PLUGINS OR USE INFORMATION GENERATED BY THESE PLUGINS, INCLUDING MAKING ANY DECISIONS BASED UPON THE INFORMATION, YOU DO SO AT YOUR OWN RISK. GREEN SOFTWARE FOUNDATION MAKES NO REPRESENTATION, GUARANTEE OR WARRANTY, EXPRESS OR IMPLIED, STATUTORY OR OTHERWISE, INCLUDING MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE NOR ANY WARRANTIES ARISING FROM COURSE OF PERFORMANCE, COURSE OF DEALING OR USAGE IN TRADE.

jmcook1186 commented 1 month ago

Also @zanete @osamajandali when we gop live can we use the following URL

https://explorer.if.greensoftware.foundation

zanete commented 1 month ago

Things to implement in the form / notion:

a process to ensure the plugin tags are comma separated - either instruct authors to fill that in the form or update the value when approving
process is that:
- The website will update every 6 hours automatically from notion
- If a deploy is needed urgently, the site should be rebuilt manually (@osamajandali will provide a link once site is deployed)

Expected next revision before the weekend cc @jmcook1186

osamajandali commented 1 month ago

All updates needed are done and it's ready to be deployed. Please take a look and let me know when to go live https://if-plugin-website.vercel.app/ cc: @zanete @jmcook1186 @zanete

jmcook1186 commented 1 month ago

Looks great @osamajandali

I think we also need the disclaimer to be on the landing page, in capitals, near the top maybe as a banner or with the text under the page title. @jawache

zanete commented 1 month ago

@osamajandali also, are the tags searchable? when I search for "food" nothing comes up (but it is a tag)

osamajandali commented 1 month ago

@jmcook1186 If we need it more visible, I'll move it to the top.

@zanete I found a good way to filter by clicking on the tag instead of using the search bar, as we agreed. Now, you can search with any term, and it will be filtered by the selected tag. Consequently, the tag is not searchable through the search bar, but I can add that feature if needed.

zanete commented 1 month ago

@osamajandali thanks for the clarification, it would make sense that searching for a tag value brings up anything that is tagged with it, so how much effort is it to make tags searchable, too?

zanete commented 1 month ago

@osamajandali thank you, works great! Let's deploy https://explorer.if.greensoftware.foundation/ if we need to bring the disclaimer to the top, we can do that closer to the official (hard) launch.

osamajandali commented 1 month ago

I've add searching with tag in the search field

The website is deployed https://explorer.if.greensoftware.foundation/

Keep in mind that the data is being fetched from notion automatically every 6 hours but if you want to trigger instant update do the following:

Go to https://github.com/Green-Software-Foundation/if-plugin-website/actions/workflows/fetch-data-notion.yml
Click on run workflow
Choose main branch

cc: @zanete @jmcook1186 @jawache

jawache commented 4 weeks ago

Hey @osamajandali, can we have the title of the card also clickable? That feels like the expected user experience, it's hard to know that the npm and GH links are what you are supposed to click. I keep on clicking the title expecting it to take me somewhere.

The logic should be it takes you to npm and if that doesn't exist then to the GitHub.

zanete commented 4 weeks ago

this will be completed this week

osamajandali commented 3 weeks ago

All fixes remaining are address now, please check it out!

Green-Software-Foundation / if

Build Plug-in Registry #684