Discover Possibilities for a Commodore Components Hub

[tobru]

Context

Discovering Commodore Components is a very important topic to spread the word an make it more approachable to interested parties. Currently we do use GitHub topics to make them discoverable: https://github.com/search?q=topic%3Acommodore-component.

We should figure out if something like Artifact Hub could help to increase visibility of Commodore Components. Either by developing / hosting an own version of a / the artifact hub or by taking part of https://artifacthub.io/.

Alternatives

Stick with GitHub topics for discoverability.

[akosma]

I think this is a super important topic. It will simplify component discovery and will open the door for third party contributions. Creating a platform around Project Syn is the most important task we can focus on to make it grow more popular every day.

There are tons of ways to do this; I would suggest this one, built upon GitHub Pull Request mechanism, in a very DevOps way:

1. Component developers submit PRs based on strict templates with required fields like repo URL, author name, version, etc
2. When the PR is merged, an HTML website is rebuilt automatically.

The first version of this website has no bells nor whistles, simply deployed in APPUiO; I think of this one as an example (if not in look & feel, in functionality): https://extensions.panic.com/ (these are plugins for a new text editor for the Mac)

We can reuse the Antora search engine we use in the Project Syn documentation for a quick search/filter feature.

At the beginning, there will be no categorization, just alphabetic order for components. For a second phase, we could think of categories to organize the components, but that should happen after we have a few dozen components in the catalog. No need to have categories with just one or two components, it just doesn't look good.

When clicking on a component, its corresponding page (which is also autogenerated) contains the README, the CHANGELOG, data from the author, and links to the repository and so on.

[akosma]

Individual component pages could also display the commands or steps required to install that component in a synthesized cluster.

[akosma]

All hosted in https://components.syn.tools – it could be yet another Antora website, at least at first.

[tobru]

I like the proposal! Some comments:

At the beginning, there will be no categorization, just alphabetic order for components. For a second phase, we could think of categories to organize the components, but that should happen after we have a few dozen components in the catalog. No need to have categories with just one or two components, it just doesn't look good.

We already have a few dozen components, in fact the search for components on GitHub already reveals "26 repository results". So I think we should have a categorization built in from the beginning.

When clicking on a component, its corresponding page (which is also autogenerated) contains the README, the CHANGELOG, data from the author, and links to the repository and so on.

We already try to have an Antora-ready /docs subdirectory on every component, see for example https://github.com/projectsyn/component-storageclass/tree/master/docs. So why not directly use these directories to render the component documentation?

Individual component pages could also display the commands or steps required to install that component in a synthesized cluster.

We could autogenerate this information as this usually is the same procedure for every component.

All hosted in https://components.syn.tools – it could be yet another Antora website, at least at first.

Yes, good idea.

This all reminds me of our VSHN internal Jira Issue [SYN-139] Integrate Commodore Component Docs into syn.tools. We might be able to leverage the idea discussed here to achieve this requirement and replace SYN-139 with this GitHub issue.

[tobru]

This has been implemented in https://github.com/projectsyn/component-hub and is available under https://hub.syn.tools/