Opened 2 years ago

Last modified 3 weeks ago

#6106 new enhancement

Deprecate readme.txt plugin name header

Reported by: dd32's profile dd32 Owned by:
Milestone: Priority: normal
Component: Plugin Directory Keywords: has-patch


Currently there's two places where the plugin name is defined:

  1. readme.txt
  2. The Plugin file

for example, for Hello Dolly:

hello.php: Plugin Name: Hello Dolly
readme.txt: === Hello Dolly ===

This duplication leads to confusion with authors, only updating one of the fields and not the other.

It's also not uncommon for authors to leave the readme as === Plugin Name === not realising that they have to replace it in both locations.

Ideally should present plugins by names that they will see after the plugin is installed, and since WordPress sites themselves do not display readme titles anywhere, having an explicit field JUST for display doesn't make sense.

Change History (15)

#1 @sebastienserre
15 months ago

I agree with @dd32. We should have to change information in only 1 place.
It will be easier and avoid some mistakes.

#2 @afragen
13 months ago

I agree. Deprecate the title in readme.txt for the purposes of displaying the plugin name.

#3 @dd32
11 months ago

I've been thinking about this again after seeing some "mistakes" in plugin names that I'm not entirely sure were not intentional.

So I've run a query over all current published plugins as of a few minutes ago, and come up with this:

Case Plugin Count Note
1. All plugins searched 60,559
2. Readme Title IS Plugin Name 46,864
🟢 These plugins are doing good.
3. Readme Title STARTS WITH Plugin Name
(but does not match)
🟡 These plugins are appending extra data to the name displayed on, SEO purposes?
For example, Plugin Name - The widgets plugin for SEO
4. Readme Title CONTAINS Plugin Name
(but does not match)
🟠 These plugins are mostly prefixing extra keywords to their plugin name, such as ACME Plugin Name.
The worst offenders are things like OtherTrademarkedPluginName - MyPluginName
5. Readme Title DOES NOT CONTAIN Plugin Name,
and Plugin Name does NOT contain Readme Name
🔴 These plugins just have a completely different name in the fields. In the best case, it's plugin-name vs Plugin Name, in the worst cases it's WP Plugin Name vs WordPress Plugin Name

I think there's probably a few steps needed to make this happen:

  1. Announce/reenforce guidelines on make/plugins.
  2. Immediately cease using Readme title for plugins in cases #4 and #5 above, use the plugin title from the plugin itself. Benefit of the doubt, that they're not intentionally trying to mislead users, and that it's just that they've missed where to update things properly.
  3. After a grace period, 1 month(?), Cease to read the readme.txt header entirely.

Due to the number of plugins which are ignoring the trademark guidelines around the usage of trademarked terms, that we reject during plugin submission, I believe we'd be likely best to enforce those with code too..

I think most people would be on the same page, that My Plugin Name - Long description about the plugin and what it does is not an appropriate plugin name, but that we also understand why the majority of plugins do this. I think we have to possibly allow it though, as the alternative is that plugin authors will simply adjust their plugin name in their php files too, such that they can continue to do so in the plugin indexes.

Last edited 11 months ago by dd32 (previous) (diff)

#4 @dd32
11 months ago

I was asked via Slack on whether this data would affect popular plugins, or if "small" plugins were the main plugins not using reasonable names. So I've broken down the above data into active install groups.

Installs 2. 🟢 Exact Match 3. 🟡 Starts with plugin name 4. 🟠 Contains plugin name 5. 🔴 Completely different
All plugins
493 plugins
2,556 plugins
8,656 plugins

Note: The data in this table has been updated since posting. A data issue was discovered with some titles resulting in some plugin being incorrectly categorised. Added the All plugins row and altered other numbers, see comment diff for the minor changes. This resulted in some plugins moving from column 5 to columns 2&3.

Last edited 11 months ago by dd32 (previous) (diff)

#5 @bordoni
11 months ago

This is really good data, and I 100% agree that if the plugin name is not the name and some one or two words for clarification it's too much. For example, when you have separators on the plugin name it's clearly because the second part is more of a description or even just for SEO purposes.

I wonder how plugins that have renamed or even re-branded after the creation of the plugin, how should they handle that process?

#6 @dd32
11 months ago

I wonder how plugins that have renamed or even re-branded after the creation of the plugin, how should they handle that process?

The vast majority of plugins that rebrand simply rename the plugin, ACME Widgets => Dions Widgets, sometimes they do have a transitional period of Dions Widgets (formally ACME Widgets) from what I've seen.

At first I don't see that being an issue at all here, it's unlikely that a plugin should/would want to have the name of the plugin on & within their users plugins panel differ.

#7 @dd32
11 months ago

In 12715:

Plugin Directory: Import: When importing plugins from SVN, if the readme title is the plugin slug, ignore that and use the Plugin headers.

This affects a minority of plugins, but this improves a small set of plugins who have === plugin-slug-here === in their readme.txt.

See #6106.

#8 @dd32
2 months ago

As noted in

If we do it for the plugin name, I'd consider also doing it for the short description. Use the one from the plugin file.

I agree that it makes sense to also switch the description field too..

This ticket was mentioned in PR #300 on WordPress/ by @dd32.

6 weeks ago

  • Keywords has-patch added

This PR removes the Plugin Name and Short Description fields from readme's, and instead uses the Plugin headers.

This is an exploration of what the changes would look like.

This ticket was mentioned in Slack in #meta by dd32. View the logs.

4 weeks ago

#11 @wplmillet
4 weeks ago

So, if I understand correctly and to exaggerate a bit, a developer who creates an extraordinary plugin will be penalized by the fact that their plugin is not translated by the community for a particular locale. I'll go further. The plugin is ultimately penalized because some strings are not validated. Most WordPress users don’t even know how extensions are translated for and by the community. Even I, who am a GPTE in fr_FR, only learned this by chance in 2020, even though I have been working on WP for much longer.

If I took ACF as an example in my case, it's simply because it's a typical situation of the principles of plugins dependent on other plugins, a kind of ecosystem within the ecosystem. Many plugins connect to it and use it. Therefore, in the readme and the strings of these plugins, there are quite a few occurrences of the searched word. It is therefore abnormal to find Yoast SEO in the first position on a search that contains just the word ACF in French. It’s not intuitive at all. If I go into the readme of Yoast SEO, there is only one occurrence of ACF. This is highly penalizing for anyone not in the US who just wants to access the plugin they are asking for. Most people who come to search just enter its name (sometimes even the one they understood). As it stands, they are certain not to find it.

There are tags, so why not make a local glossary of main tags, just like we have a translation glossary. Search engine users like Google, Bing, Yahoo, Yandex, or any other search system do just that, and users are accustomed to it. Furthermore, following the reasoning used to tell me about the failures of search, can someone explain why Wordfence is ranked first in fr_FR with only 13% of the readme translated and 42% of the plugin?

#12 follow-up: @sebastienserre
4 weeks ago

I do not understand what Translation is coming in this Trac ticket.
The goal is just to have the plugin name (which is never translated at least by the French fr_FR locale where I'm also a GPTE)

Not sure to understand your fears here @wplmillet

#13 in reply to: ↑ 12 @wplmillet
4 weeks ago

Replying to sebastienserre:

I do not understand what Translation is coming in this Trac ticket.
The goal is just to have the plugin name (which is never translated at least by the French fr_FR locale where I'm also a GPTE)

Not sure to understand your fears here @wplmillet

Oops, corrected ...sorry

#14 @dd32
3 weeks ago

In 13749:

Plugin Directory: Search: Weight the english plugin title higher for localised searches.

Most locales don't translate the readme.txt name field, and most don't alter the title at all.

When a locale doesn't translate this field (even as a 1:1 match) this results in plugins often being unable to be found by title.

This changes the weighting for the english search title from 0.00001 to 0.5 which results in the localised title being preferred, but should result in english matches still ranking in the results.

See #6106, #7617.

#15 @dd32
3 weeks ago

This also has some impacts upon localised search.

The vast majority of plugin readme's are not translated, but commonly the plugin headers are (even if it's just a 1:1 match)

This often results in search-related questions wondering why a plugin is not appearing that should, because although the name in wp-admin/plugins.php is translated, the readme.txt one used on (and therefor searching) isn't. That's the reason for the above commit being related to this ticket.

Note: See TracTickets for help on using tickets.