Skip to content

Add missing scaffold package markdown files #529

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ernilambar merged 1 commit into from
Aug 1, 2024
Merged

Add missing scaffold package markdown files #529

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 1 addition & 2 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,5 +9,4 @@ bin/packages
commands/doctor*
commands/google-sitemap*
commands/maintenance*
commands/scaffold/package*
commands/super-cache*
commands/super-cache*
41 changes: 41 additions & 0 deletions commands/scaffold/package-github.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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

<dir>
: 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. |
103 changes: 103 additions & 0 deletions commands/scaffold/package-readme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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. |
110 changes: 110 additions & 0 deletions commands/scaffold/package-tests.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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. |
83 changes: 83 additions & 0 deletions commands/scaffold/package.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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. |