Merge pull request #529 from ernilambar/fix-scaffold-package

ernilambar · web-flow · commit cc60bc1b7d2b · 2024-08-01T17:44:59.000+05:45
Add missing scaffold package markdown files
diff --git a/.gitignore b/.gitignore
@@ -9,5 +9,4 @@ bin/packages
 commands/doctor*
 commands/google-sitemap*
 commands/maintenance*
-commands/scaffold/package*
-commands/super-cache*
+commands/super-cache*
diff --git a/commands/scaffold/package-github.md b/commands/scaffold/package-github.md
@@ -0,0 +1,41 @@
+# wp scaffold package-github
+
+Generate GitHub configuration files for your command.
+
+This command runs on the `before_wp_load` hook, just before the WP load process begins.
+
+Creates a variety of files to better manage your project on GitHub. These files include:
+
+* `.github/ISSUE_TEMPLATE` - Text displayed when a user opens a new issue.
+* `.github/PULL_REQUEST_TEMPLATE` - Text displayed when a user submits a pull request.
+* `.github/settings.yml` - Configuration file for the [Probot settings app](https://probot.github.io/apps/settings/).
+
+### OPTIONS
+
+&lt;dir&gt;
+: Directory path to an existing package to generate GitHub configuration for.
+
+[\--force]
+: Overwrite files that already exist.
+
+### GLOBAL PARAMETERS
+
+These [global parameters](https://make.wordpress.org/cli/handbook/config/) have the same behavior across all commands and affect how WP-CLI interacts with WordPress.
+
+| **Argument**    | **Description**              |
+|:----------------|:-----------------------------|
+| `--path=<path>` | Path to the WordPress files. |
+| `--url=<url>` | Pretend request came from given URL. In multisite, this argument is how the target site is specified. |
+| `--ssh=[<scheme>:][<user>@]<host\|container>[:<port>][<path>]` | Perform operation against a remote server over SSH (or a container using scheme of "docker", "docker-compose", "docker-compose-run", "vagrant"). |
+| `--http=<http>` | Perform operation against a remote WordPress installation over HTTP. |
+| `--user=<id\|login\|email>` | Set the WordPress user. |
+| `--skip-plugins[=<plugins>]` | Skip loading all plugins, or a comma-separated list of plugins. Note: mu-plugins are still loaded. |
+| `--skip-themes[=<themes>]` | Skip loading all themes, or a comma-separated list of themes. |
+| `--skip-packages` | Skip loading all installed packages. |
+| `--require=<path>` | Load PHP file before running the command (may be used more than once). |
+| `--exec=<php-code>` | Execute PHP code before running the command (may be used more than once). |
+| `--context=<context>` | Load WordPress in a given context. |
+| `--[no-]color` | Whether to colorize the output. |
+| `--debug[=<group>]` | Show all PHP errors and add verbosity to WP-CLI output. Built-in groups include: bootstrap, commandfactory, and help. |
+| `--prompt[=<assoc>]` | Prompt the user to enter values for all command arguments, or a subset specified as comma-separated values. |
+| `--quiet` | Suppress informational messages. |
diff --git a/commands/scaffold/package-readme.md b/commands/scaffold/package-readme.md
@@ -0,0 +1,103 @@
+# wp scaffold package-readme
+
+Generate a README.md for your command.
+
+This command runs on the `before_wp_load` hook, just before the WP load process begins.
+
+Creates a README.md with Using, Installing, and Contributing instructions based on the composer.json file for your WP-CLI package. Run this command at the beginning of your project, and then every time your usage docs change.
+
+These command-specific docs are generated based composer.json -&gt; 'extra'
+-&gt; 'commands'. For instance, this package's composer.json includes:
+
+```
+{
+  "name": "wp-cli/scaffold-package-command",
+   // [...]
+   "extra": {
+       "commands": [
+           "scaffold package",
+           "scaffold package-tests",
+           "scaffold package-readme"
+       ]
+   }
+}
+```
+
+You can also customize the rendering of README.md generally with composer.json -&gt; 'extra' -&gt; 'readme'. For example, runcommand/hook's composer.json includes:
+
+```
+{
+    "extra": {
+        "commands": [
+            "hook"
+        ],
+        "readme": {
+            "shields": [
+                "[![Build Status](https://travis-ci.org/runcommand/reset-password.svg?branch=master)](https://travis-ci.org/runcommand/reset-password)"
+            ],
+            "sections": [
+                "Using",
+                "Installing",
+                "Support"
+            ],
+            "support": {
+                "body": "https://raw.githubusercontent.com/runcommand/runcommand-theme/master/bin/readme-partials/support-open-source.md"
+            },
+            "show_powered_by": false
+        }
+    }
+}
+```
+
+In this example:
+
+* "shields" supports arbitrary images as shields to display.
+* "sections" permits defining arbitrary sections (instead of default Using, Installing and Contributing).
+* "support" -&gt; "body" uses a remote Markdown file as the section contents. This can also be a local file path, or a string.
+* "show_powered_by" shows or hides the Powered By mention at the end of the readme.
+
+For sections, "pre", "body" and "post" are supported. Example:
+```
+"support": {
+  "pre": "highlight.md",
+  "body": "https://raw.githubusercontent.com/runcommand/runcommand-theme/master/bin/readme-partials/support-open-source.md",
+  "post": "This is additional text to show after main body content."
+},
+``` In this example:
+
+* "pre" content is pulled from local highlight.md file.
+* "body" content is pulled from remote URL.
+* "post" is a string.
+
+### OPTIONS
+
+&lt;dir&gt;
+: Directory path to an existing package to generate a readme for.
+
+[\--force]
+: Overwrite the readme if it already exists.
+
+[\--branch=&lt;branch&gt;]
+: Name of default branch of the underlying repository. Defaults to master.
+
+### GLOBAL PARAMETERS
+
+These [global parameters](https://make.wordpress.org/cli/handbook/config/) have the same behavior across all commands and affect how WP-CLI interacts with WordPress.
+
+| **Argument**    | **Description**              |
+|:----------------|:-----------------------------|
+| `--path=<path>` | Path to the WordPress files. |
+| `--url=<url>` | Pretend request came from given URL. In multisite, this argument is how the target site is specified. |
+| `--ssh=[<scheme>:][<user>@]<host\|container>[:<port>][<path>]` | Perform operation against a remote server over SSH (or a container using scheme of "docker", "docker-compose", "docker-compose-run", "vagrant"). |
+| `--http=<http>` | Perform operation against a remote WordPress installation over HTTP. |
+| `--user=<id\|login\|email>` | Set the WordPress user. |
+| `--skip-plugins[=<plugins>]` | Skip loading all plugins, or a comma-separated list of plugins. Note: mu-plugins are still loaded. |
+| `--skip-themes[=<themes>]` | Skip loading all themes, or a comma-separated list of themes. |
+| `--skip-packages` | Skip loading all installed packages. |
+| `--require=<path>` | Load PHP file before running the command (may be used more than once). |
+| `--exec=<php-code>` | Execute PHP code before running the command (may be used more than once). |
+| `--context=<context>` | Load WordPress in a given context. |
+| `--[no-]color` | Whether to colorize the output. |
+| `--debug[=<group>]` | Show all PHP errors and add verbosity to WP-CLI output. Built-in groups include: bootstrap, commandfactory, and help. |
+| `--prompt[=<assoc>]` | Prompt the user to enter values for all command arguments, or a subset specified as comma-separated values. |
+| `--quiet` | Suppress informational messages. |
diff --git a/commands/scaffold/package-tests.md b/commands/scaffold/package-tests.md
@@ -0,0 +1,110 @@
+# wp scaffold package-tests
+
+Generate files for writing Behat tests for your command.
+
+This command runs on the `before_wp_load` hook, just before the WP load process begins.
+
+WP-CLI makes use of a Behat-based testing framework, which you should use too. This command generates all of the files you need. Functional tests are an integral ingredient of high-quality, maintainable commands. Behat is a great choice as a testing framework because:
+
+* It’s easy to write new tests, which means they’ll actually get written.
+* The tests interface with your command in the same manner as your users interface with your command, and they describe how the command is expected to work in human-readable terms.
+
+Behat tests live in the `features/` directory of your project. When you use this command, it will generate a default test that looks like this:
+
+```
+Feature: Test that WP-CLI loads.
+
+  Scenario: WP-CLI loads for your tests
+    Given a WP install
+
+    When I run `wp eval 'echo "Hello world.";'`
+    Then STDOUT should contain:
+      """
+      Hello world.
+      """
+```
+
+Functional tests typically follow this pattern:
+
+* **Given** some background,
+* **When** a user performs a specific action,
+* **Then** the end result should be X (and Y and Z).
+
+View all defined Behat steps available for use with `behat -dl`:
+
+```
+Given /^an empty directory$/
+Given /^an empty cache/
+Given /^an? ([^\s]+) file:$/
+Given /^"([^"]+)" replaced with "([^"]+)" in the ([^\s]+) file$/
+```
+
+The files generated by this command include:
+
+* `.travis.yml` is the configuration file for Travis CI.
+* `bin/install-package-tests.sh` will configure your environment to run the tests.
+* `bin/test.sh` is a test runner that respects contextual Behat tags.
+* `features/load-wp-cli.feature` is a basic test to confirm WP-CLI can load.
+* `features/bootstrap`, `features/steps`, `features/extra` are Behat configuration files.
+
+After running `bin/install-package-tests.sh`, you can run the tests with `./vendor/bin/behat`. If you find yourself using Behat on a number of projects and don't want to install a copy with each one, you can `composer global require behat/behat` to install Behat globally on your machine. Make sure `~/.composer/vendor/bin` has also been added to your `$PATH`. Once you've done so, you can run the tests for a project by calling `behat`.
+
+For Travis CI, specially-named files in the package directory can be used to modify the generated `.travis.yml`, where `&lt;tag&gt;` is one of
+'cache', 'env', 'matrix', 'before_install', 'install', 'before_script', 'script':
+* `travis-&lt;tag&gt;.yml` - contents used for `&lt;tag&gt;:` (if present following ignored)
+* `travis-&lt;tag&gt;-append.yml` - contents appended to generated `&lt;tag&gt;:`
+
+You can also append to the generated `.travis.yml` with the file:
+* `travis-append.yml` - contents appended to generated `.travis.yml`
+
+### ENVIRONMENT
+
+The `features/bootstrap/FeatureContext.php` file expects the WP_CLI_BIN_DIR environment variable.
+
+WP-CLI Behat framework uses Behat ~2.5, which is installed with Composer.
+
+### OPTIONS
+
+&lt;dir&gt;
+: Directory path to an existing package to generate tests for.
+
+[\--ci=&lt;provider&gt;]
+: Create a configuration file for a specific CI provider.
+\---
+default: travis
+options:
+  - travis
+  - circle
+  - github
+\---
+
+[\--force]
+: Overwrite files that already exist.
+
+### EXAMPLES
+
+    # Generate files for writing Behat tests.
+    $ wp scaffold package-tests /path/to/command/dir/
+    Success: Created package test files.
+
+### GLOBAL PARAMETERS
+
+These [global parameters](https://make.wordpress.org/cli/handbook/config/) have the same behavior across all commands and affect how WP-CLI interacts with WordPress.
+
+| **Argument**    | **Description**              |
+|:----------------|:-----------------------------|
+| `--path=<path>` | Path to the WordPress files. |
+| `--url=<url>` | Pretend request came from given URL. In multisite, this argument is how the target site is specified. |
+| `--ssh=[<scheme>:][<user>@]<host\|container>[:<port>][<path>]` | Perform operation against a remote server over SSH (or a container using scheme of "docker", "docker-compose", "docker-compose-run", "vagrant"). |
+| `--http=<http>` | Perform operation against a remote WordPress installation over HTTP. |
+| `--user=<id\|login\|email>` | Set the WordPress user. |
+| `--skip-plugins[=<plugins>]` | Skip loading all plugins, or a comma-separated list of plugins. Note: mu-plugins are still loaded. |
+| `--skip-themes[=<themes>]` | Skip loading all themes, or a comma-separated list of themes. |
+| `--skip-packages` | Skip loading all installed packages. |
+| `--require=<path>` | Load PHP file before running the command (may be used more than once). |
+| `--exec=<php-code>` | Execute PHP code before running the command (may be used more than once). |
+| `--context=<context>` | Load WordPress in a given context. |
+| `--[no-]color` | Whether to colorize the output. |
+| `--debug[=<group>]` | Show all PHP errors and add verbosity to WP-CLI output. Built-in groups include: bootstrap, commandfactory, and help. |
+| `--prompt[=<assoc>]` | Prompt the user to enter values for all command arguments, or a subset specified as comma-separated values. |
+| `--quiet` | Suppress informational messages. |
diff --git a/commands/scaffold/package.md b/commands/scaffold/package.md
@@ -0,0 +1,83 @@
+# wp scaffold package
+
+Generate the files needed for a basic WP-CLI command.
+
+This command runs on the `before_wp_load` hook, just before the WP load process begins.
+
+Default behavior is to create the following files:
+- command.php
+- composer.json (with package name, description, and license)
+- .gitignore, .editorconfig, and .distignore
+- README.md (via wp scaffold package-readme)
+- Test harness (via wp scaffold package-tests)
+
+Unless specified with `--dir=&lt;dir&gt;`, the command package is placed in the WP-CLI `packages/local/` directory.
+
+### OPTIONS
+
+&lt;name&gt;
+: Name for the new package. Expects &lt;author&gt;/&lt;package&gt; (e.g. 'wp-cli/scaffold-package').
+
+[\--description=&lt;description&gt;]
+: Human-readable description for the package.
+
+[\--homepage=&lt;homepage&gt;]
+: Homepage for the package. Defaults to 'https://github.com/&lt;name&gt;'
+
+[\--dir=&lt;dir&gt;]
+: Specify a destination directory for the command. Defaults to WP-CLI's `packages/local/` directory.
+
+[\--license=&lt;license&gt;]
+: License for the package.
+\---
+default: MIT
+\---
+
+[\--require_wp_cli=&lt;version&gt;]
+: Required WP-CLI version for the package.
+\---
+default: ^2.5
+\---
+
+[\--require_wp_cli_tests=&lt;version&gt;]
+: Required WP-CLI testing framework version for the package.
+\---
+default: ^3.0.11
+\---
+
+[\--skip-tests]
+: Don't generate files for integration testing.
+
+[\--skip-readme]
+: Don't generate a README.md for the package.
+
+[\--skip-github]
+: Don't generate GitHub issue and pull request templates.
+
+[\--skip-install]
+: Don't install the package after scaffolding.
+
+[\--force]
+: Overwrite files that already exist.
+
+### GLOBAL PARAMETERS
+
+These [global parameters](https://make.wordpress.org/cli/handbook/config/) have the same behavior across all commands and affect how WP-CLI interacts with WordPress.
+
+| **Argument**    | **Description**              |
+|:----------------|:-----------------------------|
+| `--path=<path>` | Path to the WordPress files. |
+| `--url=<url>` | Pretend request came from given URL. In multisite, this argument is how the target site is specified. |
+| `--ssh=[<scheme>:][<user>@]<host\|container>[:<port>][<path>]` | Perform operation against a remote server over SSH (or a container using scheme of "docker", "docker-compose", "docker-compose-run", "vagrant"). |
+| `--http=<http>` | Perform operation against a remote WordPress installation over HTTP. |
+| `--user=<id\|login\|email>` | Set the WordPress user. |
+| `--skip-plugins[=<plugins>]` | Skip loading all plugins, or a comma-separated list of plugins. Note: mu-plugins are still loaded. |
+| `--skip-themes[=<themes>]` | Skip loading all themes, or a comma-separated list of themes. |
+| `--skip-packages` | Skip loading all installed packages. |
+| `--require=<path>` | Load PHP file before running the command (may be used more than once). |
+| `--exec=<php-code>` | Execute PHP code before running the command (may be used more than once). |
+| `--context=<context>` | Load WordPress in a given context. |
+| `--[no-]color` | Whether to colorize the output. |
+| `--debug[=<group>]` | Show all PHP errors and add verbosity to WP-CLI output. Built-in groups include: bootstrap, commandfactory, and help. |
+| `--prompt[=<assoc>]` | Prompt the user to enter values for all command arguments, or a subset specified as comma-separated values. |
+| `--quiet` | Suppress informational messages. |
