Making WordPress.org

Opened 4 months ago

#5792 new enhancement

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

Reported by: bedas Owned by:
Milestone: Priority: normal
Component: Plugin Directory Keywords:


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 (0)

Note: See TracTickets for help on using tickets.