Add logo for Project Browser

Perhaps you could provide some references to where this was decided and what needs to be added and why. The above link doesn't explain anything, and the related links don't explain anything, etc. I clicked through a dozen different links without finding a clear statement of how this fits into the Drupal big picture. And frankly, I shouldn't have to wade through all the discussion and history about a contributed module (Project Browser) that I don't personally use - it's your request, so please provide the background information to justify the requested changes.

I don't find any mention of Project Browser requirements in the module developers guide https://www.drupal.org/docs/develop/creating-modules → . The only documentation I find for this logo feature is in documentation specific to the Project Browser contributed module at https://www.drupal.org/docs/contributed-modules/project-browser/module-m... →

I really don't like the idea of adding a file called "logo.png" to this project at the top level. Seems to be a really poor practice and out of character with everything else in Drupal since I can't name it what I want and can't put it into a subdirectory with other images? Why isn't this something we specify in the .info.yml, or through a project browser hook? Or why can't the Project Browser maintain its own logos - it already provides default logos for projects, right?

Since there's already a logo for this project, stored on the project page, I don't see why you can't use that and simply apply an image filter if you have certain size requirements. Better yet, change the drupal.org project page so that when projects upload a logo there are certain restrictions on the file - that way your requirements will be satisfied on the front end and you can still use image filters for legacy uploads. Using the drupal.org information is how it used to work, and how it STILL works for the text description and category of the module, right? Creating a whole separate way of defining the logo does not make sense. This is not scalable or enforceable unless the logo is uploaded as a field on the project page with validation to ensure the logo is usable by the Project Browser.

This notion of requiring every contributed module to know about the needs of another contributed module (Project Browser) and to require every contributed module to add something specific in order to support the Project Browser is very un-Drupal.

Sorry if it wasn't as clear as it should have been. This issue was created before we had an issue template with more details. Will update the issue summary in the near future! Will try to counter some of your points and try to provide an answer on some as well as I go.

Perhaps you could provide some references to where this was decided and what needs to be added and why. The above link doesn't explain anything, and the related links don't explain anything, etc

Actually, all information is in the parent of the linked parent issue: 📌 [Meta] Create a logo for a contrib module Active

about a contributed module (Project Browser) that I don't personally use - it's your request, so please provide the background information to justify the requested changes.

Project Browser is part of the "Core development and strategic initiatives" more info here: https://www.drupal.org/about/core/strategic-initiatives/project-browser →

I don't find any mention of Project Browser requirements in the module developer's guide https://www.drupal.org/docs/develop/creating-modules → . The only documentation I find for this logo feature is in documentation specific to the Project Browser contributed module at https://www.drupal.org/docs/contributed-modules/project-browser/module-m → ...

I don't believe those are updated to include the requirements for the logo's. I'll circle that back to the maintainers so they can update that as well!

I really don't like the idea of adding a file called "logo.png" to this project at the top level. Seems to be a really poor practice and out of character with everything else in Drupal since I can't name it what I want and can't put it into a subdirectory with other images? Why isn't this something we specify in the .info.yml, or through a project browser hook?

No idea actually. I was not part of the initial development where it was decided that a logo should be placed in the root of a module. It probably has to do with how the search and overview logic is working. But I think this would be a great improvement to the module. I'll create an issue for that as well! Thanks 😉

Since there's already a logo for this project, stored on the project page, I don't see why you can't use that and simply apply an image filter if you have certain size requirements. Better yet, change the drupal.org project page so that when projects upload a logo there are certain restrictions on the file - that way your requirements will be satisfied on the front end and you can still use image filters for legacy uploads. Using the drupal.org information is how it used to work, and how it STILL works for the text description and category of the module, right? Creating a whole separate way of defining the logo does not make sense. This is not scalable or enforceable unless the logo is uploaded as a field on the project page with validation to ensure the logo is usable by the Project Browser.

Good point again, but I think it's similar to the point above. As the module will be installed on the end project, you don't want your site to be doing a lot of image resizing stuff on the "client" side. Having a field on the project settings could work, but I think that part was not done because it would require a change to drupal.org itself which would probably not be done as it's not part of core (yet).

If it would help to convince you, the logo.png in the project root also automatically applies to logo set in GitLab. This was decided on by the Core/Drupal.org infra team. It will also automatically show on the top left of your project page on Drupal.org. The idea is that you should not upload a logo of your project in the "images" section of your project, but actual useful screenshots or images.

Here is an example for the metatag module:
- project page (top left): https://www.drupal.org/project/metatag →
- GitLab page: https://git.drupalcode.org/project/metatag
- Project Browser screenshot: https://www.drupal.org/files/issues/2022-09-23/screen_metatag.png →

This notion of requiring every contributed module to know about the needs of another contributed module (Project Browser) and to require every contributed module to add something specific in order to support the Project Browser is very un-Drupal.

I don't believe this is the goal, that's why there is a small taskforce working on this and creating issues in all major projects. The goal was the top 100 of modules to start with. There will also be best practices in terms of short description length, amount of project categories used and the logo which we are talking about here 🙂.

Also note, maintainers are not required at all to do this. The only thing the initiative can do is to recommend maintainers to follow the best practices.

I will circle back some of your points to the maintainers to see if they could provide answers on some of the points as well 🙂.

Will set it back to needs review as the logo in the MR is following the best practices and the current implementation of Project Browser.

I think Bram has covered these points very well, but I'd just like to touch on a couple of things.

...about a contributed module (Project Browser) that I don't personally use...

I think it's important to note that Project Browser is a major initiative supported by the DA, and while it is currently a contrib module, it is expected to be in core as an experimental module, hopefully in 10.3. As it moves from experimental to a full core module, it is likely to be tightly integrated with the current module page, so while you might not use it currently, it's very likely you will in the future.

I don't find any mention of Project Browser requirements in the module developer's guide...

That's a very good point, and I'll open a discussion on that with the PB team.

I really don't like the idea of adding a file called "logo.png" to this project at the top level.

There was a lot of discussion on the best way of defining project logos, involving the drupal.org site administrators as well as the Project Browser team. For a while the Project Browser module was pulling the first image from the project images, but it was felt that this was bad practice because these images are intended for screenshots and images showing the module usage, and it is now recommended that projects using the first image field remove the logo from there. Adding a separate field for it was also considered.

I believe the logo.png image was chosen was because that's already used by GitLab (and other git based repository systems). Setting logo.png in the root of your project is a standard not exclusive to Drupal in the same way as files like README.md, LICENSE.md and composer.json. Adding this file to your project will have the logo applied to your drupalcode.org GitLab repository, the drupal.org project page (appears to the left of the project title), and to the project browser.

Thanks for all the feedback, I think it's important we take the views of module maintainers on board, and get buy-in from all parties on these changes.

Actually, all information is in the parent of the linked parent issue: #3342533: [Meta] Create a logo for a contrib module

Well no it's not. Give me some credit - like I said, I followed all the links and I *did* read through that parent meta before I replied to you. That issue is in the Project Browser issue queue and is a meta for how to create the images that the Project Browser needs. It doesn't link to any documentation on the initiative, so there's no easy way to find out where and how this logo.png decision was made, and no way for me to research that decision or participate in it to get my questions answered. That's why I'm responding here.

That issue is also not core documentation nor is it a core issue describing requirements for contributed modules. This logo.png file is not mentioned in coding standards either. There is absolutely no indication I can find that logo.png is a required element of a well-written contributed module. And as I said, we spend enormous effort to ensure that everything is configurable (even many things that no sane person would want to configure), yet the file name, format, and path is going to be hardwired?

As the module will be installed on the end project, you don't want your site to be doing a lot of image resizing stuff on the "client" side.

That's not what I was implying when I said the Project Browser could use a filter. I made the analogy with the project description text that Project Browser is currently getting from the drupal.org project page - If Project browser is already scraping this text from drupal.org to use on websites, why can't it also scrape the images and transform them in the process? Although, like I said, if this is a Drupal core initiative then there should be structural changes on drupal.org which ensure that the text and image have validations/transformations done to them when they are added to the contributed project page, that way the data is already in the correct format for project browser use. And to deal with legacy data, drupal.org can apply suitable filters to do this transformation, which act only on drupal.org, and the output of which is cached by core automatically. Or drupal.org can do this by adding a second field on the project page for the new data, and migrate the old data to the new field so that the transformation only has to be done upon migration.

I believe the logo.png image was chosen was because that's already used by GitLab (and other git based repository systems). Setting logo.png in the root of your project is a standard not exclusive to Drupal in the same way as files like README.md, LICENSE.md and composer.json. Adding this file to your project will have the logo applied to your drupalcode.org GitLab repository, the drupal.org project page (appears to the left of the project title), and to the project browser.

This is the only thing I have read which sounds like a basis for doing things this way.

So basically, because we chose GitLab as a host, and because GitLab already has magic file names that it knows how to use, Drupal contributed modules can make use of these magic file names. But that's a far cry from having these file names and file formats also standardized in Drupal. README.md, for example, is used by GitLab but officially all Drupal standards still require README.txt. Core has been indecisive for a decade about moving from .txt to .md, for example. It goes along with the whole "we support Composer but don't technically require it" transformation - Drupal refuses to make a decision to set a standard, while all along allowing the documented standard to erode until it becomes more a source of bugs than anything else. So we're constantly in transition where the old way is failing more and more but the new way is only a "suggestion" although in practice it's a requirement.

The last thing we need is a *third* redundant place where module meta information is specified - right now we have .info.yml which is required, composer.json which duplicates a lot of this information and is "technically" not required (although a lot of things like testing don't work anymore if it's not there), and magic file names where Drupal has a list of them and now GitLab also has a separate list. What happens when we need to add another piece of meta information to projects? It seems like things are diverging here - why not put new meta information requirements into composer.json and formalize the transition from .info.yml to composer.json so that in the end we only have ONE place for meta information?

Regardless, if this is a Drupal core thing, then drupal.org should be part of it by supporting this and enforcing it in the project page content type and by providing and updating the core documentation on creating and maintaining a contributed project. It should absolutely NOT be an ad hoc solution which just happens to work because GitLab defines some magic file names.

Using the images from Drupal.org project pages is a bad idea. Those could be screenshots, a logo, or anything else. There’s no standardization on what the images should be. On Drupal.org project pages, having an overly-large logo as the first image is also not great. Having the first image be used as a logo is also not clear to maintainers, and creates extra work if they don’t have a logo and just want to upload a screenshot.

If we had kept down that path, we would have added a separate logo field. But GitLab already supports something good for this, and we are using it. The logo appears to the left of the title on https://git.drupalcode.org/project/project_browser and https://www.drupal.org/project/project_browser → . There is already Drupal.org integration of this, and it is effectively official policy.

The documentation is indeed lacking. This should be in the canonical documentation instead of project browser documentation.