Merge pull request #418 from WordPress/add/build-step-docs

Add docs for building the plugin

.distignore

@@ -0,0 +1,42 @@
+.git
+.github
+.idea
+.wordpress-org
+build
+build-cs
+build-phpunit
+docs
+node_modules
+patches
+test-content
+tests
+
+*.DS_Store
+.DS_Store
+.distignore
+.editorconfig
+.eslintrc.js
+.gitattributes
+.gitignore
+.nvmrc
+.phpunit.result.cache
+.wp-env.json
+.wp-env.override.json
+behat.yml
+CODE_OF_CONDUCT.md
+codecov.yml
+composer.json
+composer.lock
+CONTRIBUTING.md
+package.json
+package-lock.json
+phpcs.xml
+phpcs.xml.dist
+phpmd.xml
+phpstan.neon
+phpstan.neon.dist
+phpunit.xml
+phpunit.xml.dist
+plugin-check.iml
+README.md
+SECURITY.md

.github/workflows/deploy.yml

@@ -14,6 +14,11 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v3
 
+      - name: Install PHP dependencies
+        uses: ramsey/composer-install@83af392bf5f031813d25e6fe4cd626cdba9a2df6
+        with:
+          composer-options: '--prefer-dist --no-progress --no-interaction --no-dev'
+
       - name: WordPress Plugin Deploy
         id: deploy
         uses: 10up/action-wordpress-plugin-deploy@stable

assets/js/plugin-check-admin.js

@@ -89,7 +89,7 @@
 	/**
 	 * Reset the results container.
 	 *
-	 * @since n.e.x.t
+	 * @since 1.0.0
 	 */
 	function resetResults() {
 		// Empty the results container.
@@ -99,7 +99,7 @@
 	/**
 	 * Resets the form controls once checks have completed or failed.
 	 *
-	 * @since n.e.x.t
+	 * @since 1.0.0
 	 */
 	function resetForm() {
 		spinner.classList.remove( 'is-active' );
@@ -113,7 +113,7 @@
 	/**
 	 * Setup the runtime environment if needed.
 	 *
-	 * @since n.e.x.t
+	 * @since 1.0.0
 	 *
 	 * @param {Object} data Data object with props passed to form data.
 	 */
@@ -153,7 +153,7 @@
 	/**
 	 * Cleanup the runtime environment.
 	 *
-	 * @since n.e.x.t
+	 * @since 1.0.0
 	 *
 	 * @return {Object} The response data.
 	 */
@@ -186,7 +186,7 @@
 	/**
 	 * Get the Checks to run.
 	 *
-	 * @since n.e.x.t
+	 * @since 1.0.0
 	 */
 	function getChecksToRun() {
 		const pluginCheckData = new FormData();
@@ -230,7 +230,7 @@
 	/**
 	 * Run Checks.
 	 *
-	 * @since n.e.x.t
+	 * @since 1.0.0
 	 *
 	 * @param {Object} data The response data.
 	 */
@@ -259,7 +259,7 @@
 	/**
 	 * Renders result message.
 	 *
-	 * @since n.e.x.t
+	 * @since 1.0.0
 	 *
 	 * @param {boolean} isSuccessMessage Whether the message is a success message.
 	 */
@@ -279,7 +279,7 @@
 	/**
 	 * Run a single check.
 	 *
-	 * @since n.e.x.t
+	 * @since 1.0.0
 	 *
 	 * @param {string} plugin The plugin to check.
 	 * @param {string} check  The check to run.
@@ -314,7 +314,7 @@
 	/**
 	 * Handles any errors in the data returned from the response.
 	 *
-	 * @since n.e.x.t
+	 * @since 1.0.0
 	 *
 	 * @param {Object} data The response data.
 	 * @return {Object} The response data.
@@ -340,7 +340,7 @@
 	/**
 	 * Renders results for each check on the page.
 	 *
-	 * @since n.e.x.t
+	 * @since 1.0.0
 	 *
 	 * @param {Object} results The results object.
 	 */
@@ -365,7 +365,7 @@
 	/**
 	 * Renders the file results table.
 	 *
-	 * @since n.e.x.t
+	 * @since 1.0.0
 	 *
 	 * @param {string} file     The file name for the results.
 	 * @param {Object} errors   The file errors.
@@ -397,7 +397,7 @@
 	/**
 	 * Checks if there are any links in the results object.
 	 *
-	 * @since n.e.x.t
+	 * @since 1.0.0
 	 *
 	 * @param {Object} results The results object.
 	 * @return {boolean} True if there are links, false otherwise.
@@ -418,7 +418,7 @@
 	/**
 	 * Renders a result row onto the file table.
 	 *
-	 * @since n.e.x.t
+	 * @since 1.0.0
 	 *
 	 * @param {string}  type     The result type. Either ERROR or WARNING.
 	 * @param {Object}  results  The results object.
@@ -454,7 +454,7 @@
 	/**
 	 * Renders the template with data.
 	 *
-	 * @since n.e.x.t
+	 * @since 1.0.0
 	 *
 	 * @param {string} templateSlug The template slug
 	 * @param {Object} data         Template data.

cli.php

@@ -5,12 +5,12 @@
  * This is necessary to setup the environment to perform runtime checks.
  *
  * @package plugin-check
- * @since n.e.x.t
+ * @since 1.0.0
  */
 
 use WordPress\Plugin_Check\Checker\CLI_Runner;
-use WordPress\Plugin_Check\Plugin_Context;
 use WordPress\Plugin_Check\CLI\Plugin_Check_Command;
+use WordPress\Plugin_Check\Plugin_Context;
 
 if ( ! defined( 'WP_CLI' ) || ! WP_CLI ) {
 	return;
@@ -40,14 +40,14 @@
 /**
  * Adds hook to set up the object-cache.php drop-in file.
  *
- * @since n.e.x.t
+ * @since 1.0.0
  */
 WP_CLI::add_hook(
 	'before_wp_load',
-	function() {
+	function () {
 		if ( CLI_Runner::is_plugin_check() ) {
 			if ( ! file_exists( ABSPATH . 'wp-content/object-cache.php' ) ) {
-				if ( ! copy(  __DIR__ . '/drop-ins/object-cache.copy.php', ABSPATH . 'wp-content/object-cache.php' ) ) {
+				if ( ! copy( __DIR__ . '/drop-ins/object-cache.copy.php', ABSPATH . 'wp-content/object-cache.php' ) ) {
 					WP_CLI::error( 'Unable to copy object-cache.php file.' );
 				}
 			}

docs/README.md

@@ -4,3 +4,4 @@
 * [Creating a Static Check](creating-a-static-check.md)
 * [Creating a Runtime Check](creating-a-runtime-check.md)
 * [CLI Commands](CLI.md)
+* [Releasing a New Version of Plugin](releasing.md)

docs/creating-a-static-check.md

@@ -53,7 +53,7 @@ class My_Custom_Check extends Abstract_PHP_CodeSniffer_Check {
    *
    * Every check must have at least one category.
    *
-   * @since n.e.x.t
+   * @since 1.0.0
    *
    * @return array The categories for the check.
    */
@@ -88,7 +88,7 @@ use WordPress\Plugin_Check\Traits\Stable_Check;
 /**
  * Check for detecting incorrect casing of the term "WordPress" (specifically "Wordpress") using string search in files.
  *
- * @since n.e.x.t
+ * @since 1.0.0
  */
 class My_Custom_Check extends Abstract_File_Check {
 
@@ -99,7 +99,7 @@ class My_Custom_Check extends Abstract_File_Check {
    *
    * Every check must have at least one category.
    *
-   * @since n.e.x.t
+   * @since 1.0.0
    *
    * @return array The categories for the check.
    */
@@ -110,7 +110,7 @@ class My_Custom_Check extends Abstract_File_Check {
   /**
    * Check the "Wordpress" in files.
    *
-   * @since n.e.x.t
+   * @since 1.0.0
    *
    * @param Check_Result $result The Check Result to amend.
    * @param array        $files  Array of plugin files.
@@ -160,7 +160,7 @@ Below is an example demonstrating how to access the plugin context and add messa
 /**
  * Runs the check on the plugin and amends results.
  *
- * @since n.e.x.t
+ * @since 1.0.0
  *
  * @param Check_Result $result The check results to amend and the plugin context.
  */

docs/releasing.md

@@ -0,0 +1,36 @@
+[Back to overview](./README.md)
+
+# Releasing a New Version of Plugin
+
+This project uses a [GitHub Action workflow](../.github/workflows/deploy.yml) for automatically deploying
+stable releases of Plugin Check to the [WordPress plugin directory](https://wordpress.org/plugins/plugin-check/), so there is no manual build step involved.
+
+Follow these steps:
+
+1. Bump the `Version` field in the main plugin file's header.
+2. Bump `WP_PLUGIN_CHECK_VERSION` in the same file.
+3. Bump the `Stable tag` field in the `readme.txt` file.
+4. Update the changelog in `readme.txt`.
+5. Commit this to the default branch.
+6. On GitHub, go to "Releases" and create a new release.
+7. Once published, this release will be automatically deployed to the plugin directory.
+
+## Building the Plugin
+
+If you would like to manually replicate the build process locally, you can do so
+using the [`wp dist-archive` WP-CLI command](https://github.com/wp-cli/dist-archive-command/).
+In your terminal, you can run this in the directory where you checked out this repository:
+
+```
+# Ensure PHPCS is installed, as it is required for some of the checks.
+composer install --no-dev
+# Build the ZIP file.
+wp dist-archive . /path/to/write/the/plugin-check.zip
+```
+
+Note: you might first need to install the WP-CLI command if it's not yet available:
+
+```
+wp package install wp-cli/dist-archive-command
+```
+

drop-ins/object-cache.copy.php

@@ -19,7 +19,7 @@
  * be using, and it is implemented in a way that there is no risk for breakage.
  *
  * @package plugin-check
- * @since n.e.x.t
+ * @since 1.0.0
  */
 
 // Set constant to be able to later check for whether this file was loaded.