Update documentation for module maintainers with location of logo.png file

Created on 18 January 2023, almost 2 years ago
Updated 8 February 2023, almost 2 years ago

Problem/Motivation

In issue 📌 [PLAN] Where to fetch image from? Fixed , proposal #3 is to attach the project logo to the root of the GitLab repo. This will allow GitLab to make use of the logo for the repository.

Current documentation for module maintainers states that project logo should be the first image in the project.

It would make sense to start encouraging project maintainers to place logo.png in the root of their project. Even if proposal #3 isn't selected, it is still useful to have the logo available for GitLab, so there doesn't seem to be any disadvantage. Solution #3 seems to have a reasonable amount of support in the other issue, so if it is chosen, adding to the documentation would mean that module maintainers would start including logos in their repos earlier, speeding up adoption.

Document located at: https://www.drupal.org/docs/contributed-modules/project-browser/module-m...

Steps to reproduce

Proposed resolution

In the #Logo section of the document step 4 currently reads:

4. Upload the logo to your module description page, by making sure it is the first image if you upload more than one (ex.g.: some additional screenshots)

Replacing with:

4. Place the logo in the root directory of the Git repository for your project, on the default branch. The logo file should be named logo.png. The logo will be placed on Drupal.org project pages, to the left of the project name. For example Project Browser has a logo.png file. Logos are cached and may take up to an hour to show.

Remaining tasks

  • ✅ File an issue about this project
  • ☐ Manual Testing
  • ☐ Code Review
  • ☐ Accessibility Review
  • ☐ Automated tests needed/written?

Followup tasks

Draft guidance on what makes a good image.

Feature request
Status

Fixed

Version

1.0

Component

Documentation

Created by

🇮🇪Ireland lostcarpark

Live updates comments and jobs are added and updated live.
Sign in to follow issues

Comments & Activities

Not all content is available!

It's likely this issue predates Contrib.social: some issue and comment data are missing.

  • Status changed to Needs review almost 2 years ago
  • 🇮🇪Ireland lostcarpark

    I would appreciate any feedback on the proposed change to the documentation for module maintainers.

  • 🇪🇸Spain fjgarlin

    Mostly agree with everything. Tweaking a few things to try to get the terminology right but it's mostly the same:

    4. Upload the logo to your module description page, by making sure it is the first image if you upload more than one (e.g.: some additional screenshots). This is currently selected by the beta versions of Project Browser. When the final version of Project Browser launches ( 📌 Prepare to switch to using (the future) Drupal 9 JSON:API endpoint - implement tests, etc. Fixed ), the logo will be taken from a field whose URL will default to GitLab's project avatar (see next step), so the first image will no longer be used as logo anymore.

    5. Place the logo in the root directory of the project repository for the main branch. The logo file should be named "logo.png". By doing this, GitLab will take that image as the project's avatar. These logos are currently showing in the current version drupal.org module pages, to the left of the project name, e.g. https://www.drupal.org/project/project_browser .

  • 🇮🇪Ireland lostcarpark

    Thanks @fjgarlin, I agree the wording in #5 is an improvement.

  • 🇺🇸United States drumm NY, US

    Upload the logo to your module description page, by making sure it is the first image if you upload more than one (e.g.: some additional screenshots). This is currently selected by the test version of the Drupal 9 endpoint used by Project Browser. However, when the new endpoint goes live, Project Browser will no longer use the first image.

    I do not think this is good advice. We should not ask project maintainers to put in extra work to put up an image just for testing project browser, when they should remove it soon. It also takes up space on the current Drupal.org project pages with a duplicated image, which would be better as a screenshot or other descriptive image.

    This should be removed for now. A followup can add guidance on what makes a good image.

    This is now used by the Drupal 7 site on drupal.org

    The instructions should be straightforward for project maintainers, we don’t need to go into what Drupal.org is running; and it will get outdated in the long run.

  • 🇺🇸United States drumm NY, US

    Updating the issue summary with another draft based on fjgarlin’s draft in #5.

    Key changes:

    • Default branch, not main. Main might be confused with a branch named main
    • Mentioned caching, they take up to an hour to display.
    • Don’t need to mention too many technical details like GitLab or avatar.
  • 🇺🇸United States drumm NY, US

    Added a small clarification to the first sentence.

    And added “Followup tasks” to the issue summary.

  • 🇮🇪Ireland lostcarpark

    Thanks @drumm. Very well put. I think that you're right that we should give one set of instructions going forward, not ask maintainers to make multiple changes.

  • 🇺🇸United States chrisfromredfin Portland, Maine

    Should we mention that maintainers can also not include logo.png, but it could be named something else and they can manually set the avatar in their GitLab settings? I imagine this matters little for module maintainers, but may become important for theme maintainers.

  • 🇺🇸United States drumm NY, US

    they can manually set the avatar in their GitLab settings

    We don’t actually allow that right now. We have to block GitLab’s project editing since it allows features we can’t support (like continuous deployment and monitoring-related things, which don’t make sense for modules/themes/etc) and getting the project out of sync with Drupal.org (like renaming it)

    may become important for theme maintainers

    I haven't been able to find where logo.png is special for themes. Not many of the themes I spot checked use it. I think it’s just a convention for where to put the default logo for the theme. And default logos aren’t necessarily great, if I’m starting a site, I’d rather have well-rendered text with the ability to replace with a logo; not a default logo I must replace.

  • Status changed to RTBC almost 2 years ago
  • 🇺🇸United States chrisfromredfin Portland, Maine

    I think the current proposal is adequate for the needed change, esp. in light of Drumm's insight that we currently can't change the avatar through the GitLab settings, so let's keep it simple for now, and to the point. And this is ultimately is what we want folks to do, so I say let's go!

  • Status changed to Fixed almost 2 years ago
  • 🇺🇸United States chrisfromredfin Portland, Maine

    Thank you, James!

  • Automatically closed - issue fixed for 2 weeks with no activity.

Production build 0.71.5 2024