Naming conventions for revamped badge art files

Project Discussion
1

Hi folks- in our last badges community roundtable we briefly discussed naming conventions for the revamped badge art files. It came up again today in the Fedora Badges channel, and we thought it would be good to open a discussion thread to make sure we are getting different perspectives and have an easily findable record of our conversation around the topic.

Some perspectives from the channel:

  • My first proposal was “(category) _ (ticketnumber) _ (shorttitle).svg” and “(category)
    _ (ticketnumber) _ (shorttitle).png”
  • @smeragoel responds: I think it sounds good, I’m trying to think of any practical problems we could run into with this naming scheme. I like that we have the category and ticket number included, definitely will make sorting and searching easier
  • @gui1ty responds: I would drop the ticket number. Once we move to GitLab and have badge requests there, these numbers will get duplicated, which could potentially lead to conflicts. I do like including the category. For the file names I would suggest using the slugs of the badge page. For Red Hat Summit 2023 that would be ‘red-hat-summit-2023.png’.
  • @gui1ty follows up with: Could we also use subdirectories for the categories instead of putting it in the file name? I think that looks cleaner and, imho, is clearer.

I personally agree with the possibility that duplicate ticket numbers from pagure/gitlab could cause confusion so I think leaving that out seems good. I am also okay with using subdirectories per category but I don’t know if that causes and potential issues or complications for the backend or automation. So @gui1ty’s proposal boils down to using the slug from each Badges page, which is okay by me. The only potential issue I see is retaining that convention moving forward.

Please feel free to add any input. A note: We do need to make a decision pretty quickly as we have two badge design interns starting next week to work on the project.

1 Like
2

On second thought, it was also suggested in the past that we move all tickets from Pagure to GitLab. However, we lack the tooling to do that in a consistent fashion.

To give some more background, in the early days of badges, the Badges repo was hosted on GitHub and so were the issues, including badge request. That’s why some of the older badges, e.g. the tester series, still have a GitHub link in the Criteria field. That repo is now archived (still available for viewing).
So there is already some conflict in referencing tickets.

On the other hand, we could go down that same route and keep the Pagure issue tracker as a public archive for reference, thereby also making a clear distinction between 1.0 and 2.0 badges.

I don’t think it does now.[1] It just adds to the path on the webserver. Keeping with the same example as above, the image URL is https://badges.fedoraproject.org/pngs/tester-06.png. That would become https://badges.fedoraproject.org/pngs/quality/tester-06.png.

For Badges 2.0, since it will be rewritten from the ground up, we can make sure subdirs will not cause any issues.

That has occurred to me as well. To make matters worse, the naming of badges already lacks consistency. I just noticed that again today, when I created the Release Party badge for F38. Go to https://badges.fedoraproject.org/explore and search for release party. It’s a myriad of names[2]. :slightly_frowning_face:

To make matters more complicated, some special characters like '() are removed from the badge name when creating the slug, while others (!) are not. That leads to HTML escape sequences in the slug, while the badge name retains the special character in the database.[3]

One possible way out would be to work primarily with merge requests. Allowing for changes, including file names, to be reviewed. Right now, everyone who is in sysadmin-badges can push directly to the Pagure repo.

This turned out to be a longer brain drain than I anticipated. Food for thought!

  1. This is very easy to test by simply pushing a badge image inside a subdir and checking if it’s accessible on the server. I’ll do that to confirm my assumption. ↩︎

  2. Similar things can be said about tags, by the way. ↩︎

  3. I suppose that’s something we need to take care of during development. ↩︎

3

I like the idea of including the category in the slug and since we have so many badges, I think using directories makes sense.

I don’t know if we have ever tried using sub-directories for badges before. It might be worth an experimental push to the repo just to see if the badge artwork is pushed to the front-end server how we’d expect it to.

4

Hmmm, it seems to me there are potential issues any which way we go about it. I agree that using sub directories for each category of badge will eliminate the need to add the categories to the file name. I think as it stands, the use of sub directories is the best thing we can get out of this discussion, and that will give us a place to start when looking for the art files.

Because each badge is getting designed individually and by a variety of individuals- I think keeping a rigidly consistent naming convention will be difficult outside of things like categories or ticket numbers (which we decided aren’t a great idea). From what I understand badge admins are handling each badge design individually, as well. The badge admin could potentially change the file names when moving the art to the sub directories- but then there is a disconnect between the files on the ticket and the directories.

Unless someone else has other ideas, I am satisfied with sub directories + “do the best we can” and manage each badge individually. I think there is a saying for this sort of thing: “naming things is hard” :wink:

5

That’s already the case. I make every effort to name recurring badges in line with the previous names. If there are already multiple names, I choose what seems most appropriate [1] to me.

Regarding categories, I would suggest putting all known categories into the issue tracker as labels. When a new badge is requested, we make sure all appropriate labels are selected and only these labels will be added as tags to the badge. Cross-referencing with previous badges should happen to determine what tags have been assigned in the past.

I just did that and can confirm that added sub-directories work just fine in the current setup:


https://infrastructure.fedoraproject.org/infra/badges/pngs/event/rhsummit2023.png

And naming things consistently is even harder. Yet, we can make an effort to better document naming guidelines and make sure files are named appropriately and consistently when processing merge requests.

  1. Appropriate in terms of clarity and conventions. The current documentation states:
    Make sure files have a reasonable name (e.g. all-lowercase-dashes-only.png ). Some types of badges follow a naming convention, like FAS group membership badges (i.e. fas-badge-name.png ) or Koji build badges (i.e. koji-badge-name.png ). Follow past precedent where possible. Later, the file name is used for the file on the front-end server (e.g. https://badges.fedoraproject.org/pngs/all-lowercase-dashes-only.png ). ↩︎

6

Hi everyone,

I’m thinking of a hybrid solution. By hybrid solution, this is what I mean:

  • Use subdirectories: This will keep things organized, as @gui1ty said.
  • Use category_shorttitle.ext format: I think that it would be easier to identify where a file belongs, even if (for example) it’s lost from its directory in a future migration.

We’d get a result something like this:

category0/
     category0_shorttitle.ext
     category0_shortertitle.ext
     category0_longertitle.ext
     category0_notitle.ext
category1/
     category1_shorttitle.ext
     category1_shortertitle.ext
     category1_longertitle.ext
     category1_notitle.ext

P.S. @riecatnor said:

using sub directories for each category of badge will eliminate the need to add the categories to the file name

I think this may actually be useful :face_holding_back_tears:, in that it preservers the purpose of the file within its name. A similar method is used in many projects for organizing source code, for instance. I don’t know if that would be too cumbersome for other maintainers?

7

I’m okay with that. Although, I don’t think files “get lost” in a VCS easily. :wink: