Discussion: How to make the projects portal customizeable

[dellagustin]

As mentioned on the the ISC Community Call InnerSource and Discoverability, one of our ideas for the portal is to make it customizeable.

What is the problem?

Currently, the way to reuse the portal is to fork it and modify it, it is not reusable in the sense of being a customizeable dependency that can be reused without modifications.

One of the cons of this approach is that it is harder to keep it up to integrate updates, as there may be conflicts between the changes on the original repo and the forks.

Here are some of the features that could be customizeable:

• favicon
• logo
• style and colors
• link to contribute (see Add contributing link to the header #25)

What is this issue about

I created this issue to collect ideas on how we could make the portal customizeable.

Features we should keep

One of the great features of the portal today is that it can be easily hosted as static files. This make it easy to operate, as it can be hosted for instance on GitHub pages. When making customizeable, we should aim to keep it for simplicity.

[spier]

This is an interesting angle to make it easier to reuse the project and contribute to it.

Some other ideas where customizability could be helpful:

• link to "add new project" (orange ➕ sign at the bottom right) - Links to https://yourcompany.corp/innersource-instructions by default right now.
• default sort order for the projects in the portal (I think right now the default is "Activity", even though the activity score is a custom
• contact information for the company-internal maintainer of the portal - e.g. if somebody is browsing the portal and something doesn't look right, who should they contact?
• an predefined approach to add custom pages to the portal (e.g. a menu from where one could link to other resources that a given company considers relevant in relation to their InnerSource Portal)

[dellagustin-sap]

@spier #26 (comment) all good considerations.

[dellagustin-sap]

I'm thinking about how I'd like the experience to be from a developer's perspective reusing the portal.
I am picturing something like this:

1. I initialize an npm package for my own portal:

   npm init
   

2. I install the "portal reusable" as a dependency

   npm install --save @sap/project-portal-for-innersource
   

   depending on how we do it, could be --save-dev
3. I start it with

   npm start
   

   or build it for deployment with (it would output something deployable to the dist folder)

   npm run build
   

4. I configure the portal, maybe by adding a section to package.json, or creating a folder on the root of the project, like portal-config.json

[svrnm]

A suggestion for the portability:

Rename repos.json to repos.sample.json and add repos.json to .gitignore, update the README.md with the extra step of cp repos.sample.json repos.json

That way if the sample data gets updated I don't get merge conflicts when I pull from upstream.

[zkoppert]

👋 One thing I've done to customize the portal for a few companies is to insert any "Overview metrics" right at the top just above the search bar and filters. This is done through a nightly automation to keep the stats fresh.

Example:

---

"424 InnerSource repositories, 10% of all repositories, 21hr average time to first response on Pull requests, Average security score: 90"

---

[dellagustin-sap]

Hi @svrnm, this is an interesting suggestion. I'll discuss it with @Michadelic.

@zkoppert , that's an interesting customization, thanks for sharing!

[svrnm]

thanks @dellagustin

[Michadelic]

Amazing list of suggestions to customize the portal. Thank you so much for bringing these ideas together and the discussion here in this thread. I will have a look and i am also very open for public contributions on this issue. Maybe we can jointly create a concept and work on it.

My two cents for getting it implemented:

• have a config.json file as @dellagustin-sap suggested in the root directory and adjust the portal so that it reads the config file instead of hard-coded values in the portal. Then the config file can be updated at any time to adjust the beahvior and content of the portal
• have a templating wizard connected to the npm init command to fill the config.json file interactively by asking with the comments defined in the config.json file. This would need a json format that supports comments or a separate file for the wizard. The wizard can also be used to update existing values at any time and readjust the portal behavior.

We could start with the config.json file and the list of suggestions in this thread and later add the wizard.

What do you thing?

PS: the overview metrics is also an interesting idea. This would probably done in the crawler at the end and update an entry in the config.json file?

[svrnm]

Having a configuration to fill out the page details is a great idea! It also helps to find all the things that need to be changed since on the HTML page they are at very different places 👍

A few other suggestions:

• a thing I just learned while trying the portal out, is that npm is currently only used for pulling in some dependencies via the postinstall and then it uses http-server, so it is possible to run the portal without npm and with my "preferred" (or available) webserver, for example I can just do php -S localhost:8080 and it works, or I can put it into a nginx container, or I can use GitHub Pages (see below)! It would be great to have those alternatives documented.

• Additionally, it would be great if the HTML + assets (styles, JS, JSON files) would live in their own directory, because then when hosted not all other files of the repository are exposed via the HTTP server.

• making peoples' live extra easy the name of the folder could be docs/, because this is the only other path GH allows besides /:
  

  Here is a prototype how this could look like: https://svrnm.github.io/project-portal-for-innersource/#display=card

• Finally, while looking into this option I was wondering if it wouldn't be an option to leverage jekyll or hugo instead of npm for building and configuration?

[Morl99]

I want to chime in with a link to a project that we use internally, that fulfills a lot of the requirements discussed here. Maybe it can serve as an example:

https://github.com/AOEpeople/aoe_technology_radar

We have our own instance of that techradar, customized it to our CI and deploy it on GitLab Pages (which is working like GitHub pages). It works really well and updating it is a task that renovate does for us (with the exception of major updates, of course). Maybe it can serve as an inspiration.

For your reference: Thanks to our chat about this, I am now looking into adapting this portal for us. If it turns out that it would be useful for us, I will be happy to actively contribute to some of the aspects mentioned in this issue (no promises just yet).

[dellagustin-sap]

Hello @Morl99, thank you for sharing the https://github.com/AOEpeople/aoe_technology_radar, I did a quick check on the README and it seems that what they have is very similar to what I would like to offer with our portal, so a very good reference.