Make WordPress Core

Opened 4 months ago

Closed 4 months ago

#53527 closed enhancement (reported-upstream)

Update readme documentation to better reflect code usage, and clarify a discrepancy with the Readme validator

Reported by: bedas Owned by:
Milestone: Priority: normal
Severity: normal Version: 5.7.2
Component: Plugins Keywords:
Focuses: docs Cc:


When submitting a Plugin readme.txt file, the instructions [here]https://developer.wordpress.org/plugins/wordpress-org/how-your-readme-txt-works/ does not specify that we need to add the code within <pre><code></code></pre> tags.

Instead, it states that code "goes within backticks"
This is only correct for one-line code.
For multiple lines of code (for example an "example filter") this is not working, and we need to use code and pre tags instead.

It would be good to update/reflect that on the DOC, so no one needs to "test what works"

Here is a text suggestion, where in https://developer.wordpress.org/plugins/wordpress-org/how-your-readme-txt-works/#example-readme, the line <?php code(); // goes in backticks ?>

<?php code(); // goes in backticks ?>
<pre><code> //larger code goes into pre and code tags
<?php add_filter( 'hook', 'example', 10, 1 );
function example(){
//do stuff

In the same doc, https://developer.wordpress.org/plugins/wordpress-org/how-your-readme-txt-works/#readme-header-information does not mention anything about the Requires PHP field.
However, when we validate a readme with https://wordpress.org/plugins/developers/readme-validator/, then the following warning will appear:

The Requires PHP field is missing. It should be defined here, or in your main plugin file.

That warning might confuse people (it did confuse me).
This could perhaps be mentioned in the DOC, that when we use the validator, we can ignore this warning, as the field is "obsolete" as it seems this field was once added to readme in past by mistake, and while this has been corrected, the validator does not reflect that. Thus a DOC mention could help clarify that.

Change History (1)

#1 @SergeyBiryukov
4 months ago

  • Keywords needs-docs removed
  • Milestone Awaiting Review deleted
  • Resolution set to reported-upstream
  • Status changed from new to closed

Hi there, welcome to WordPress Trac! Thanks for the ticket.

Please note that this Trac is used for enhancements and bug reporting for the WordPress core software. Any issues or ideas for WordPress.org sites, including the Plugin Directory, should be reported on https://meta.trac.wordpress.org.

I've transferred the report to #meta5792. Thanks again!

Note: See TracTickets for help on using tickets.