Merge pull request #323 from WordPress/docs/300-revise-readme-txt

Revise `readme.txt` for new version

README.md

@@ -1,8 +1,6 @@
 # Plugin Check
 
-This repository is for the WordPress plugin checker, a tool for plugin developers to analyze their plugin code and flag any violations or concerns around plugin development best practices, from basic requirements like correct usage of internationalization functions to accessibility, performance, and security best practices.
-
-The WordPress plugin checker was [first proposed in summer 2022](https://make.wordpress.org/plugins/2022/07/05/proposal-for-a-wordpress-plugin-checker/) and is now at an early MVP stage.
+Plugin Check is a WordPress.org tool which provides checks to help plugins meet the directory requirements and follow various best practices.
 
 ## Features
 

composer.json

@@ -1,6 +1,6 @@
 {
   "name": "wordpress/plugin-check",
-  "description": "Plugin Check plugin from the WordPress Performance Team, a collection of tests to help improve plugin performance.",
+  "description": "Plugin Check is a WordPress.org tool which provides checks to help plugins meet the directory requirements and follow various best practices.",
   "type": "wordpress-plugin",
   "license": "GPL-2.0-or-later",
   "require": {

plugin-check.php

@@ -2,7 +2,7 @@
 /**
  * Plugin Name: Plugin Check
  * Plugin URI: https://github.com/WordPress/plugin-check
- * Description: Plugin Check plugin from the WordPress Performance Team, a collection of tests to help improve plugin performance.
+ * Description: Plugin Check is a WordPress.org tool which provides checks to help plugins meet the directory requirements and follow various best practices.
  * Requires at least: 6.3
  * Requires PHP: 7.0
  * Version: n.e.x.t

readme.txt

@@ -1,24 +1,33 @@
-
 === Plugin Check ===
 
 Contributors:      wordpressdotorg
 Requires at least: 6.3
-Tested up to:      6.3
+Tested up to:      6.4
 Requires PHP:      7.0
 Stable tag:        n.e.x.t
 License:           GPLv2 or later
 License URI:       https://www.gnu.org/licenses/gpl-2.0.html
-Tags:              performance, testing, security
+Tags:              plugin best practices, testing, accessibility, performance, security
 
-Plugin Check plugin from the WordPress Performance Team, a collection of tests to help improve plugin performance.
+Plugin Check is a WordPress.org tool which provides checks to help plugins meet the directory requirements and follow various best practices.
 
 == Description ==
 
-The Plugin Check is an easy way of testing your plugin and ensure that it's up to the base required standards from the Plugin Review team. With this plugin you will be able to run most of the checks used by the team, and check if your plugin meets the requirements.
+Plugin Check is a tool for testing whether your plugin meets the required standards for the WordPress.org plugin directory. With this plugin you will be able to run most of the checks used for new submissions, and check if your plugin meets the requirements.
+
+Additionally, the tool flags violations or concerns around plugin development best practices, from basic requirements like correct usage of internationalization functions to accessibility, performance, and security best practices.
+
+The checks can be run either using the WP Admin user interface or WP-CLI:
+
+* To check a plugin using WP Admin, please navigate to the _Tools > Plugin Check_ menu. You need to be able to manage plugins on your site in order to access that screen.
+* To check a plugin using WP-CLI, please use the `wp plugin check` command. For example, to check the "Hello Dolly" plugin: `wp plugin check hello.php`
+    * Note that by default when using WP-CLI, only static checks can be executed. In order to also include runtime checks, a workaround is currently necessary using the `--require` argument of WP-CLI, to manually load the `cli.php` file within the plugin checker directory before WordPress is loaded. For example: `wp plugin check hello.php --require=./wp-content/plugins/plugin-check/cli.php`
+
+The checks are grouped into several categories, so that you can customize which kinds of checks you would like to run on a plugin.
 
-The tests are run through a simple admin menu and all results are displayed at once. This is very handy for plugin developers, or anybody looking to make sure that their plugin supports the [latest WordPress plugin standards and practices](https://make.wordpress.org/plugins/handbook/performing-reviews/review-checklist/).
+Keep in mind that this plugin is not a replacement for the manual review process, but it will help you speed up the process of getting your plugin approved for the WordPress.org plugin repository, and it will also help you avoid some common mistakes.
 
-Keep in mind that this plugin is not yet a replacement for the manual review process, but it will help you speed up the process of getting your plugin approved for the WordPress.org plugin repository, and it will also help you avoid some common mistakes.
+Even if you do not intend to host your plugin in the WordPress.org directory, you are encouraged to use Plugin Check so that your plugin follows the base requirements and best practices for WordPress plugins.
 
 == Installation ==
 
@@ -40,20 +49,24 @@ Keep in mind that this plugin is not yet a replacement for the manual review pro
 
 All development for this plugin is handled via [GitHub](https://github.com/WordPress/plugin-check/) any issues or pull requests should be posted there.
 
-= What if the plugin reports as "error" something that's correct? =
+= What if the plugin reports something that's correct as an "error" or "warning"? =
 
-We strived to write a plugin in a way that minimizes false positives but If you find one, please report it in the GitHub repo.
-
-If you can, please consider submitting a Pull Request to fix it.
+We strive to write a plugin in a way that minimizes false positives but if you find one, please report it in the GitHub repo. For certain false positives, such as those detected by PHPCodeSniffer, you may be able to annotate the code to ignore the specific problem for a specific line.
 
 = Why does it flag something as bad? =
 
-It's not flagging "bad" things, as such. The plugin check is designed to be a non-perfect way to test for compliance with the [Plugin Review guidelines](https://make.wordpress.org/plugins/handbook/performing-reviews/review-checklist/). Not all plugins must adhere to these guidelines. The purpose of the checking tool is to ensure that plugins uploaded to the [central WordPress.org plugin repository](https://wordpress.org/plugins/) meet the latest standards of WordPress plugin and will work on a wide variety of sites.
+It's not flagging "bad" things, as such. Plugin Check is designed to be a non-perfect way to test for compliance with the [Plugin Review guidelines](https://make.wordpress.org/plugins/handbook/performing-reviews/review-checklist/), as well as additional plugin development best practices in accessibility, performance, security and other areas. Not all plugins must adhere to these guidelines. The purpose of the checking tool is to ensure that plugins uploaded to the [central WordPress.org plugin repository](https://wordpress.org/plugins/) meet the latest standards of WordPress plugin and will work on a wide variety of sites.
 
 Many sites use custom plugins, and that's perfectly okay. But plugins that are intended for use on many different kinds of sites by the public need to have a certain minimum level of capabilities, in order to ensure proper functioning in many different environments. The Plugin Review guidelines are created with that goal in mind.
 
 This plugin checker is not perfect, and never will be. It is only a tool to help plugin authors, or anybody else who wants to make their plugin more capable. All plugins submitted to WordPress.org are hand-reviewed by a team of experts. The automated plugin checker is meant to be a useful tool only, not an absolute system of measurement.
 
+= Does a plugin need to pass all checks to be approved in the WordPress.org plugin directory? =
+
+To be approved in the WordPress.org plugin directory, a plugin must typically pass all checks in the "Plugin repo" category. Other checks are additional and may not be required to pass.
+
+In any case, passing the checks in this tool likely helps to achieve a smooth plugin review process, but is no guarantee that a plugin will be approved in the WordPress.org plugin directory.
+
 == Changelog ==
 
 = [0.2.1] 2023-09-22 =

tests/phpunit/testdata/plugins/test-plugin-code-obfuscation-ioncube-errors/load.php

@@ -2,7 +2,7 @@
 /**
  * Plugin Name: Test Plugin Code Obfuscation ionCube Errors
  * Plugin URI: https://github.com/WordPress/plugin-check
- * Description: Plugin Check plugin from the WordPress Performance Team, a collection of tests to help improve plugin performance.
+ * Description: Some plugin description.
  * Author: WordPress Performance Team
  * Author URI: https://make.wordpress.org/performance/
  * License: GPLv2 or later

tests/phpunit/testdata/plugins/test-plugin-code-obfuscation-sourceguardian-errors/load.php

@@ -2,7 +2,7 @@
 /**
  * Plugin Name: Test Plugin Code Obfuscation Source Guardian Errors
  * Plugin URI: https://github.com/WordPress/plugin-check
- * Description: Plugin Check plugin from the WordPress Performance Team, a collection of tests to help improve plugin performance.
+ * Description: Some plugin description.
  * Author: WordPress Performance Team
  * Author URI: https://make.wordpress.org/performance/
  * License: GPLv2 or later

tests/phpunit/testdata/plugins/test-plugin-code-obfuscation-zendguard-errors/load.php

@@ -2,7 +2,7 @@
 /**
  * Plugin Name: Test Plugin Code Obfuscation Zend Guard Errors
  * Plugin URI: https://github.com/WordPress/plugin-check
- * Description: Plugin Check plugin from the WordPress Performance Team, a collection of tests to help improve plugin performance.
+ * Description: Some plugin description.
  * Author: WordPress Performance Team
  * Author URI: https://make.wordpress.org/performance/
  * License: GPLv2 or later

tests/phpunit/testdata/plugins/test-plugin-file-type-application-errors/load.php

@@ -2,7 +2,7 @@
 /**
  * Plugin Name: Test Plugin File Type Application Errors
  * Plugin URI: https://github.com/wordpress/plugin-check
- * Description: Plugin Check plugin from the WordPress Performance Team, a collection of tests to help improve plugin performance.
+ * Description: Some plugin description.
  * Author: WordPress Performance Team
  * Author URI: https://make.wordpress.org/performance/
  * License: GPLv2 or later

tests/phpunit/testdata/plugins/test-plugin-file-type-compressed-errors/load.php

@@ -2,7 +2,7 @@
 /**
  * Plugin Name: Test Plugin File Type Compressed Errors
  * Plugin URI: https://github.com/WordPress/plugin-check
- * Description: Plugin Check plugin from the WordPress Performance Team, a collection of tests to help improve plugin performance.
+ * Description: Some plugin description.
  * Author: WordPress Performance Team
  * Author URI: https://make.wordpress.org/performance/
  * License: GPLv2 or later

tests/phpunit/testdata/plugins/test-plugin-file-type-phar-errors/load.php

@@ -2,7 +2,7 @@
 /**
  * Plugin Name: Test Plugin File Type PHAR Errors
  * Plugin URI: https://github.com/WordPress/plugin-check
- * Description: Plugin Check plugin from the WordPress Performance Team, a collection of tests to help improve plugin performance.
+ * Description: Some plugin description.
  * Author: WordPress Performance Team
  * Author URI: https://make.wordpress.org/performance/
  * License: GPLv2 or later

tests/phpunit/testdata/plugins/test-plugin-file-type-vcs-hidden-errors/load.php

@@ -2,7 +2,7 @@
 /**
  * Plugin Name: Test Plugin File Type VCS Hidden Errors
  * Plugin URI: https://github.com/WordPress/plugin-check
- * Description: Plugin Check plugin from the WordPress Performance Team, a collection of tests to help improve plugin performance.
+ * Description: Some plugin description.
  * Author: WordPress Performance Team
  * Author URI: https://make.wordpress.org/performance/
  * License: GPLv2 or later

tests/phpunit/testdata/plugins/test-plugin-header-text-domain-with-errors/load.php

@@ -2,7 +2,7 @@
 /**
  * Plugin Name: Test Plugin Header Text Domain without errors for Plugin Check
  * Plugin URI: https://github.com/WordPress/plugin-check
- * Description: Plugin Check plugin from the WordPress Performance Team, a collection of tests to help improve plugin performance.
+ * Description: Some plugin description.
  * Requires at least: 6.0
  * Requires PHP: 5.6
  * Version: n.e.x.t

tests/phpunit/testdata/plugins/test-plugin-header-text-domain-without-errors/load.php

@@ -2,7 +2,7 @@
 /**
  * Plugin Name: Test Plugin Header Text Domain without errors for Plugin Check
  * Plugin URI: https://github.com/WordPress/plugin-check
- * Description: Plugin Check plugin from the WordPress Performance Team, a collection of tests to help improve plugin performance.
+ * Description: Some plugin description.
  * Requires at least: 6.0
  * Requires PHP: 5.6
  * Version: n.e.x.t

tests/phpunit/testdata/plugins/test-plugin-i18n-usage-errors/load.php

@@ -2,7 +2,7 @@
 /**
  * Plugin Name: Test Plugin i18n usage with Errors for Plugin Check
  * Plugin URI: https://github.com/WordPress/plugin-check
- * Description: Plugin Check plugin from the WordPress Performance Team, a collection of tests to help improve plugin performance.
+ * Description: Some plugin description.
  * Requires at least: 6.0
  * Requires PHP: 5.6
  * Version: n.e.x.t

tests/phpunit/testdata/plugins/test-plugin-i18n-usage-without-errors/load.php

@@ -2,7 +2,7 @@
 /**
  * Plugin Name: Test Plugin i18n usage without errors for Plugin Check
  * Plugin URI: https://github.com/WordPress/plugin-check
- * Description: Plugin Check plugin from the WordPress Performance Team, a collection of tests to help improve plugin performance.
+ * Description: Some plugin description.
  * Requires at least: 6.0
  * Requires PHP: 5.6
  * Version: n.e.x.t

tests/phpunit/testdata/plugins/test-plugin-ignore-directories/load.php

@@ -2,7 +2,7 @@
 /**
  * Plugin Name: Test Plugin i18n usage with Errors for Plugin Check
  * Plugin URI: https://github.com/wordpress/plugin-check
- * Description: Plugin Check plugin from the WordPress Performance Team, a collection of tests to help improve plugin performance.
+ * Description: Some plugin description.
  * Requires at least: 6.0
  * Requires PHP: 5.6
  * Version: n.e.x.t

tests/phpunit/testdata/plugins/test-plugin-late-escaping-errors/load.php

@@ -2,7 +2,7 @@
 /**
  * Plugin Name: Test Plugin escape output with Errors for Plugin Check
  * Plugin URI: https://github.com/WordPress/plugin-check
- * Description: Plugin Check plugin from the WordPress Performance Team, a collection of tests to help improve plugin performance.
+ * Description: Some plugin description.
  * Requires at least: 6.0
  * Requires PHP: 5.6
  * Version: n.e.x.t

tests/phpunit/testdata/plugins/test-plugin-late-escaping-without-errors/load.php

@@ -2,7 +2,7 @@
 /**
  * Plugin Name: Test Plugin late escaping without errors for Plugin Check
  * Plugin URI: https://github.com/WordPress/plugin-check
- * Description: Plugin Check plugin from the WordPress Performance Team, a collection of tests to help improve plugin performance.
+ * Description: Some plugin description.
  * Requires at least: 6.0
  * Requires PHP: 5.6
  * Version: n.e.x.t

tests/phpunit/testdata/plugins/test-plugin-performant-wp-query-params-errors/load.php

@@ -2,7 +2,7 @@
 /**
  * Plugin Name: Test Plugin Performant WP_Query with errors
  * Plugin URI: https://github.com/WordPress/plugin-check
- * Description: Plugin Check plugin from the WordPress Performance Team, a collection of tests to help improve plugin performance.
+ * Description: Some plugin description.
  * Requires at least: 6.0
  * Requires PHP: 5.6
  * Version: n.e.x.t

tests/phpunit/testdata/plugins/test-plugin-performant-wp-query-params-without-errors/load.php

@@ -2,7 +2,7 @@
 /**
  * Plugin Name: Test Plugin Performant without errors for Plugin Check
  * Plugin URI: https://github.com/WordPress/plugin-check
- * Description: Plugin Check plugin from the WordPress Performance Team, a collection of tests to help improve plugin performance.
+ * Description: Some plugin description.
  * Requires at least: 6.0
  * Requires PHP: 5.6
  * Version: n.e.x.t

tests/phpunit/testdata/plugins/test-plugin-update-uri-header-errors/load.php

@@ -2,7 +2,7 @@
 /**
  * Plugin Name: Test Plugin Update URI Header Errors for Plugin Check
  * Plugin URI: https://github.com/WordPress/plugin-check
- * Description: Plugin Check plugin from the WordPress Performance Team, a collection of tests to help improve plugin performance.
+ * Description: Some plugin description.
  * Requires at least: 6.0
  * Requires PHP: 5.6
  * Version: n.e.x.t

tests/phpunit/testdata/plugins/test-plugin-updater-file-errors/load.php

@@ -2,7 +2,7 @@
 /**
  * Plugin Name: Test Plugin Updater File Errors for Plugin Check
  * Plugin URI: https://github.com/WordPress/plugin-check
- * Description: Plugin Check plugin from the WordPress Performance Team, a collection of tests to help improve plugin performance.
+ * Description: Some plugin description.
  * Requires at least: 6.0
  * Requires PHP: 5.6
  * Version: n.e.x.t

tests/phpunit/testdata/plugins/test-plugin-updater-routines-errors/load.php

@@ -2,7 +2,7 @@
 /**
  * Plugin Name: Test Plugin Updater Routines Errors for Plugin Check
  * Plugin URI: https://github.com/WordPress/plugin-check
- * Description: Plugin Check plugin from the WordPress Performance Team, a collection of tests to help improve plugin performance.
+ * Description: Some plugin description.
  * Requires at least: 6.0
  * Requires PHP: 5.6
  * Version: n.e.x.t

tests/phpunit/testdata/plugins/test-plugin-updater-routines-regex-errors/load.php

@@ -2,7 +2,7 @@
 /**
  * Plugin Name: Test Plugin Updater Routines Errors for Plugin Check
  * Plugin URI: https://github.com/WordPress/plugin-check
- * Description: Plugin Check plugin from the WordPress Performance Team, a collection of tests to help improve plugin performance.
+ * Description: Some plugin description.
  * Requires at least: 6.0
  * Requires PHP: 5.6
  * Version: n.e.x.t

tests/phpunit/testdata/plugins/test-plugin-updaters-errors/load.php

@@ -2,7 +2,7 @@
 /**
  * Plugin Name: Test Plugin Updaters Errors for Plugin Check
  * Plugin URI: https://github.com/WordPress/plugin-check
- * Description: Plugin Check plugin from the WordPress Performance Team, a collection of tests to help improve plugin performance.
+ * Description: Some plugin description.
  * Requires at least: 6.0
  * Requires PHP: 5.6
  * Version: n.e.x.t

tests/phpunit/testdata/plugins/test-plugin-updaters-regex-errors/load.php

@@ -2,7 +2,7 @@
 /**
  * Plugin Name: Test Plugin Updaters Errors for Plugin Check
  * Plugin URI: https://github.com/WordPress/plugin-check
- * Description: Plugin Check plugin from the WordPress Performance Team, a collection of tests to help improve plugin performance.
+ * Description: Some plugin description.
  * Requires at least: 6.0
  * Requires PHP: 5.6
  * Version: n.e.x.t