wp-cli / handbook Goto Github PK

Once wp-cli/package-command#20 has been implemented, we need to add documentation about what syntax can be used for version constraints.

I think the "Setting up" steps in "Pull Requests" should include the initial forking, eg

1. Fork the WP-CLI repository.
2. Clone your forked repository to your local machine: git clone https://github.com/<your-name>/wp-cli ~/wp-cli
3. Install Composer etc...

Also using the "https:" style of request will work for everyone.

To better communicate how pull requests are considered, we should create a "Code Review" document explaining code review procedures.

@goldenapples wrote wise words in https://github.com/fusioneng/tech-docs/blob/0d53f3da41e0bec4511f3b4a63e6b4fc528da865/team-culture/code-review.md#what-code-review-is that we can crib from.

Right now, the handbook is mostly a reference, with tips and tutorials sprinkled throughout.

Apart from the "Quickstart" guide, there's no real user manual that explains all the concepts for a new user in a linear progression.

I'd like to plan for a real "User Manual" with a clean list of linear chapters that takes new users by the hand and provides a proper introduction that can be read from start to finish.

Trying to update WP-CLI 1.5.x nightly build to latest stable release.

Getting CURL timeout & SSL error.

Last Error:
Error: Failed to get url 'https://github.com/wp-cli/wp-cli/releases/download/v1.5.0/wp-cli-1.5.0.phar': cURL error 56: SSL read: error:00000000:lib(0):func(0):reason(0), errno 104.****

From Slack:

I've read a lot of articles and watched videos from WCs. Wondering as a hoster with multiple sites, how I would target those installs (spread across different cpanel /home/* directories) to install and activate a plugin. The plugin commands are straightforward, but what I'm not clear on (and don't find in docs) is if I can target those WordPress installs from a global WP-CLI install, and how I would do that. Thanks.

WP-CLI aliases are a good fit for this: wp-cli/wp-cli#2039 (comment)

Our annotated wp-cli.yml file makes them hidden though:

We should document aliases in a dedicated sub-section.

From wp-cli/ideas#58 (comment)

It's missing because it's in utils-wp.php, which isn't loaded until after WordPress is loaded. wp handbook api-dump is run before WordPress is loaded.

Several links are incorrect now as we have moved to make site.

Like, current link for documentation standards is https://make.wordpress.org/docs/documentation-standards/

Correct link https://make.wordpress.org/cli/handbook/documentation-standards/

If you want to provide a flag that can optionally include a value, the syntax is --foo[=<bar>].

If you want to make that flag with an optional value entirely optional as well, the syntax is [--foo[=<bar>]].

This needs to be documented in the command cookbook.

tee is a useful utility if you want to capture and display output from a command. We should mention it, and document its usage, in the "Save command output" section.

https://github.com/wp-cli/handbook/blob/master/shell-friends.md

From zao-web/cli-framework#5 (comment)

Command short descriptions should match WordPress PHP documentation standard:
https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/php/#meta-language-packs

The documenation guidelines need to be adapted:
https://make.wordpress.org/cli/handbook/documentation-standards/#command-annotation

Formatting typo causing the last word in the summary to be orphaned in the notes sub section.

https://make.wordpress.org/cli/handbook/internal-api/wp-cli-run-command/

Related wp-cli/wp-cli#4302

For instance (see wp-cli/wp-cli#4302 (comment)) the shell command description (https://developer.wordpress.org/cli/commands/shell/) renders as

<code>wp shell</code> allows you to evaluate PHP statements and expressions
<br>
interactively, from within a WordPress environment. Type a bit of code,
<br>
...

when it should just render without the <br>s and let the browser wrap it.

The documentation to make WP-CLI available on remote servers found at https://make.wordpress.org/cli/handbook/running-commands-remotely/#making-wp-cli-accessible-on-a-remote-server is skipping the most obvious way of achieving this and should be adapted.

The simplest way to achieve this:

1. Create a folder ~/bin and move WP-CLI binary into ~/bin/wp
2. Add export PATH="$HOME/bin:$PATH" to ~/.profile (or ~/.bash_profile) file

From wp-cli/wp-cli#4105

I'm happy to start this document, but I need some guidance.

The idea being a 'how to setup wp-cil on a development environment for a first timer'

Considering things like LAMP. MAMP, WAMP, Vagrant (and possibly Docker) in terms of what people use for development environments.

WP-CLI supports aliases for Docker images, but this isn't mentioned in the documentation for running commands remotely.

https://make.wordpress.org/cli/handbook/internal-api/wp-cli-runcommand/

The example code block is not parsed correctly, curly quotes, a single - instead of --

If you put some text (e.g. "Example:") in between the unordered list and the code block, the latter will be correctly highlighted

Our Philosophy document would benefit from greater detail around the decision-making process. We should do a pass on revising it.

These docs need to move to WordPress.org:

Hit list:

• Write a WP-CLI command to generate markdown docs for internal APIs.
• Write a WP-CLI command to generate a manifest file of the handbook.
• Update make/cli to import the manifest file.
• Set up CloudFlare redirects for internal API docs
• Finalize formatting of the internal API page.
• Document how all of this works.

From https://meta.trac.wordpress.org/ticket/2465

It came to my understanding recently that WP-CLI does not translate its strings. I'd recommend adding this to the documentation.

While trying to confirm it, I looked at it and could not find any information. Someone was kind to show me this feedback: https://wordpress.slack.com/archives/C02RP4T41/p1511796963000358

See wp-cli/i18n-command#80

From https://meta.trac.wordpress.org/ticket/3629:

https://make.wordpress.org/cli/handbook/installing/#installing-via-homebrew

The following command no longer works as homebrew/php is now deprecated:
brew install homebrew/php/wp-cli
WP-CLI can now be installed simply with:
brew install wp-cli
Link to formula also needs updating.

https://developer.wordpress.org/cli/commands/

From Write the Docs April newsletter:

First up this month, someone asked the channel for a good example of how to document a bug. The community came through with suggestions for a template that includes:

Environment: affected software and versions
Summary in narrative form, such as “While testing feature x, I encountered z.”
Steps to reproduce the bug
Results and impacts, including severity level
Workarounds
Relevant diagnostics

It'd be good to get this worked into https://make.wordpress.org/cli/handbook/bug-reports/

The handbook is currently being generated against the latest master versions. This causes issues where the handbook documents functionality that has not been released yet, like in wp-cli/media-command#15

We should discuss how to best handle this. I see three general approaches that are commonly being used for such documentation:

1. Always build handbook against latest released versions only, so that the handbook does not contain stuff that is not generally available yet. This is the easiest approach, and is a safe compromise.

2. Build two separate versions of the handbook (stable|nightly or similar), that the users can switch to and from as needed. This covers most use cases.

3. Build the handbook for every released version + master (0.23.0|1.0.0|1.1.0|nightly or similar), that the users can switch from. This is the complete solution that makes sure that even users that rely on legacy versions get reliable documentation.

This document should describe the standards the maintainers hold themselves to.

Now that the project consists of many sub-components, it's not clear how to (or whether it's necessary to) run all tests for all commands.

Points of note:

• If a contributor makes a change to a command in a sub-component, is it sufficient to run just the tests for that particular sub-component?
• If a contributor makes a change to the bootstrap functionality, how can they run the tests for all of the commands to ensure nothing unexpected breaks?
• The bin/test.sh script that lives in every sub-component command has a dependency on the behat executable being installed globally. It should instead run Behat from the root vendor/bin/behat executable if possible.

Ref: https://make.wordpress.org/cli/handbook/pull-requests/

Related: #17.

I just updated WP-CLI and saw these odd warnings.

You have version 1.1.0. Would you like to update to 1.2.0? [y/n] y
Downloading from https://github.com/wp-cli/wp-cli/releases/download/v1.2.0/wp-cli-1.2.0.phar...

Warning: strtotime(): It is not safe to rely on the system's timezone settings. You are *required* to use the date.timezone setting or the date_default_timezone_set() function. In case you used any of those methods and you are still getting this warning, you most likely misspelled the timezone identifier. We selected the timezone 'UTC' for now, but please set date.timezone to select your timezone. in phar:///usr/local/bin/wp/vendor/rmccue/requests/library/Requests/Cookie.php on line 262

Warning: strtotime(): It is not safe to rely on the system's timezone settings. You are *required* to use the date.timezone setting or the date_default_timezone_set() function. In case you used any of those methods and you are still getting this warning, you most likely misspelled the timezone identifier. We selected the timezone 'UTC' for now, but please set date.timezone to select your timezone. in phar:///usr/local/bin/wp/vendor/rmccue/requests/library/Requests/Cookie.php on line 262
md5 hash verified: ffa57fd2d992b5329795ba9501ae8085
New version works. Proceeding to replace.
Success: Updated WP-CLI to 1.2.0.

It is minor in the grand scheme of things. Props to another awesome release!

WP-CLI integration test documentation exists in two places:

• https://make.wordpress.org/cli/handbook/pull-requests/#running-and-writing-tests
• https://github.com/wp-cli/scaffold-package-command#wp-scaffold-package-tests

It would be more user-friendly to have an uberdoc for Behat tests. We could have two sections:

1. Introduction - Getting started, and writing your first test
2. Advanced usage - Now that you've written a test, here's how you write steps, etc.

Once this document exists, we can have both existing places link directly to it.

Related https://deliciousbrains.com/writing-functional-tests-wp-cli-packages/

Sometimes, a pull request submitted by a new contributor needs to be closed for one reason or another. How the committer communicates the closure can strongly influence whether the contributor feels positive or negative about the experience.

We should identify some best practices for closing a pull request and document them in the handbook. I'm undecided as to whether "Code review" or "Repository management" is the best place for this; open to suggestions.

We should have a document specifically focused on the different ways a WP-CLI can be run against multiple sites:

• WP-CLI aliases
• Use wp find to produce a list of paths.

From wp-cli/ideas#39

Related https://danielbachhuber.com/tip/run-wp-cli-command-wordpress-multisite/

The wp core config command has been changed into wp config create, and the docs should reflect this.

Now that there are multiple people merging pull requests, closing issues and tagging releases, I think it's a good time to codify some repository management standards.

This document should include detail on:

• Labeling #16
• Tagging releases / release note format.
• Milestone usage.
• Versioning.

We should add a section on available support channels (taken from http://wp-cli.org/#support) and link to that section in an obvious way from the gray ribbon at the top of the CLI site.

It's now incorrect in some ways.

• Reference who has commit access, and the standards they're held to #30
• Update WP-CLI homepage to link to the Governance document.

When something does not work as expected, most users don't really know how to go about diagnosing the issue. We already have a "Common Issues" document, but I think it would be very useful to also have a "Trobuleshooting Guide" document, that explains things like:

• how plugins & themes can interfere with WP-CLI and how to skip them
• how config files can interfere with WP-CLI and how to find out which ones are being loaded
• how third-party commands can interfere with WP-CLI and how to find out which ones are loaded and how to skip them
• …

It would be nice if these were nested into their own folder:

Currently the handbook repo does not have any license. I guess MIT should work in this case but I'm not sure as this doc is hosted on make.wordpress.org which may or may not have a policy of having all code in GPL.

This document assumes that you have already tried setting up WP Unit Testing environment for your project in windows but have stucked somewhere.

The purpose of this discussion is to perfectly set up WP Unit Testing environment in a local project. Followed through https://make.wordpress.org/cli/handbook/plugin-unit-tests/ but it lacks some points when it comes to windows with addition to some general points missing.

First, some commands in wp-cli doesnt work with windows, so use cygwin or alike command line utility.
Cygwin is preferred because its suggested even in Working With Patches – Make WordPress Core.

Before starting, let me suggest that if you fail with running wp scaffold command then update your wp-cli to stable version first (Ex : wp cli update --nightly)

For ease of understanding, I rewrite the points of above mentioned tutorial, such as ...

2. Generate the plugin test files:

   wp scaffold plugin-tests my-plugin

It would work perfectly when you are running it on WordPress downloaded with wp core download but when you run this command in any local WordPress setup, which is not downloaded from above, it would generate error :

Error: This does not seem to be a WordPress install.
Pass --path=path/to/wordpress or run wp core download.

Which is valid cause its not installed from wp-cli, run the wp core download and it will create src with WordPress in it (The folder structure of core WordPress installation).

Running plugin-tests command can still generate error like ....

Error: 'wp-config.php' not found.
Either create one manually or use wp config create.

Now, running wp config create will create wp-config.php file in src installation.

3. Initialize the testing environment locally: cd into the plugin directory and run the install script. (You’ll need to already have svn and wget installed.)

bash bin/install-wp-tests.sh wordpress_test root '' localhost latest

bash script does not work directly in windows. In windows10, they have introduced "Windows Subsystem for Linux" but in other versions of windows, you need to do separate work for running bash. Cygwin by default runs the bash scripts.

For running above bash script, not only svn and wget but svn and either wget or curl are required because of the following lines in install-wp-tests.sh script

download() { if [ which curl]; then curl -s "$1" > "$2"; elif [which wget ]; then wget -nv -O "$2" "$1" fi }

Again, which is a linux command not by default in windows, it can be installed as a package. All curl, svn and wget can be installed in windows as packages, but for running bash you need to be depending on third party tools, Cygwin in our case.

Bash script is bound to build wordpress over there right after wordpress-tests-lib because of mkdir -p $WP_CORE_DIR in install-wp-tests.sh file but it sometimes fails because its a tmp folder and so sometimes it depends on whether or not tmp folder is perfectly emptied or not. If in any case WordPress folder does not get created there, then you can set up one manually. The logic is, while running any tests, it runs them against this WordPress in /tmp/wordpress-tests-lib. So finally in your /tmp folder there should be structure like this ...

1. data
2. includes
3. WordPress
4. wp-tests-config.php file

Finally run phpunit and there you go.....

Hope, above mentioned tutorial helps.

Sometimes contributor pull requests get left without tests:

• wp-cli/wp-cli#4164
• wp-cli/wp-cli#4182

We should document how these can be cleaned up by committers, so they aren't orphaned.

We should produce a Repo standards document that has a subsection on labeling. Specifically:

• What labels each package repository should have.
• How to determine which labels an issue should receive.

The wish list document wish-list.md is outdated and not being used anymore and should be removed.

Wish list items and feature requests should be collected in https://github.com/wp-cli/ideas/issues instead.

Hit list:

• Write a WP-CLI command to generate markdown docs for commands.
• Write a WP-CLI command to generate a manifest file of the commands.
• Update developer.wp.org to import the manifest file.
• Create an archive page listing all commands.
• Set up CloudFlare redirects for commands
• Finalize formatting of the command page.
• Document how all of this works.

Related #32

From https://meta.trac.wordpress.org/ticket/2465

Regarding the common problem PHP Fatal error: Allowed memory size of 999999 bytes exhausted.

The first example (editing the php.ini file) changes the memory_limit to 512M. However, the second example for setting the memory_limit on the fly temporarily changes it to 256M. For my server, this was not sufficient - I needed to set it to 512M as suggested in the previous example. So, I am thinking this may be a typo in the docs and that those troubleshooting this issue may have more success with 512M.

I can create a pull request for the issue but I'm not 100% I'm not sure if this is something that does need fixing, so I decided to start with creating an issue :)

The documentation at https://make.wordpress.org/cli/handbook/config/#environment-variables is missing the WP_CLI_PHP environment variable

Now that the project is being split into subcomponents, it'd be good to revisit the "Contributing" document and associated workflows.

On a whole, I think we need one large CONTRIBUTING.md that links to a variety of deeper how-to guides as needed. Our current CONTRIBUTING.md is too shallow, which means the reader quickly is scattered in a variety of directions.

Some specific improvements to make:

• Open an issue to discuss new features.
• One logical change per pull request.
• Pull requests are expected to have tests. Pull requests without tests are a rare exception.

Some inspiration:

• http://docs.python-requests.org/en/master/dev/contributing/

We should port over this: https://danielbachhuber.com/tip/identify-plugin-theme-conflict-wp-cli/

WP-CLI is licensed under the MIT license, and all bundled code should be compatible with that.

We should document our licensing expectations for:

• accepting third-party code into the official repository/organization
• bundling third-party code
• depending on third-party code

Related: wp-cli/wp-config-transformer#1 (comment)