Clarify the options for `icon` in catalog-info.yaml

openedx / open-edx-proposals

Proposals for Open edX architecture, best practices and processes

http://open-edx-proposals.readthedocs.io/

Other

43 stars 32 forks source link

Clarify the options for `icon` in catalog-info.yaml #568

Open robrap opened 4 months ago

robrap commented 4 months ago

The use of icon should be clarified in the docs for catalog-info.yaml: https://github.com/openedx/open-edx-proposals/edit/master/oeps/processes/oep-0055/decisions/0001-use-backstage-to-support-maintainers.rst

The following list is very clear, it gives the acceptable type values:

# (Required) Acceptable Type Values: service, website, library
type: 'website'

Here are the current docs for icon:

# Backstage uses the MaterialUI Icon Set.
# https://mui.com/material-ui/material-icons/
# The value will be the name of the icon.
icon: "Web"

What it would be useful to know is:

Do we simply want to use "Web" for everything, do we want to give users a small enumerated list, or do we allow choosing from anything in the icon set?
Do we want to use 3 standard icons that match the type values of service, website, or library?
Do we want other icons to be used? If so, under what circumstances?

robrap commented 4 months ago

@feanil: I should probably open a separate ticket, but I just noticed that the proposed type for https://github.com/openedx/edx-repo-health is 'other'. I think type needs at least one more value of other, or tool, or utility, or something of this nature. Thoughts?

sarina commented 2 months ago

@feanil could you provide any insight here? What would you like to see from this icon field?

feanil commented 1 month ago

I honestly have no opinion on what the value of Icon should be, it's meant to be representative of the link that it is associated with. The lack of guidance on the icon is because I don't think it needs guidance. I guess we could say that if you're not sure about what to choose, just choose the "Web" icon? Would that be helpful?

sarina commented 1 month ago

I've poked around backstage and I don't even see the use of this "web" icon:

anywhere. Do we need this field?

On the Search page I see an icon for "Software Catalog"

On the Home page I see no icons, and when I click in to a repo like https://backstage.openedx.org/catalog/default/component/openedx-learning i similarly don't see this icon.

feanil commented 1 month ago

The icon defines the bit highlighted in this image in red:

It's just for the specific link in the links list and not related to the rest of the backstage representation for a catalog resource.

sarina commented 1 month ago

Ah gotcha. That icon doesn't match the "Web" icon from https://mui.com/material-ui/material-icons/ so I missed it.

If the icon set Backstage uses doesn't even match the one that's linked, it'll be difficult to pick an appropriate alternate. I'm inclined to say we should just always use "Web".