Getting Started Docs: Update to use `wp-env` #20044

ockham · 2020-02-05T08:32:19Z

Description

There's apparently a build step currently missing from the Getting Started docs.

How has this been tested?

If you just follow the current Getting Started instructions up until npm run env install, you'll see the following at http://localhost:8889/ :

None of the suggestions listed there actually work. Instead, you have to cd wordpress/ && npm run dev. Thanks to @noahtallen for pointing this out to me:

I got this issue on a fresh install yesterday and I had to run npm run dev from the Wordpress folder (which is one directory inside Gutenberg if you don’t have an existing setup)

(Adding that I'm seeing this on Linux, but it's probably not OS specific -- I don't think Noah is using Linux?)

Types of changes

Doc change

Checklist:

I've included developer documentation if appropriate.

gziolo · 2020-02-05T08:58:30Z

I think it's time to deprecate this setup and replace it with @wordpress/env. It doesn't make sense to keep 2 different environments and maintain them in parallel. cc @epiqueras

ockham · 2020-02-05T10:28:35Z

I think it's time to deprecate this setup and replace it with @wordpress/env. It doesn't make sense to keep 2 different environments and maintain them in parallel. cc @epiqueras

Can you point me to up-to-date instructions on how to run Gutenberg locally? 😅 Since apparently I don't know.

FWIW, I arrived at this doc through https://github.com/WordPress/Gutenberg -> 'Please see CONTRIBUTING.md.' -> 'Code? See the developer section.' -> 'Getting Started.' 🍿

Are you saying that that isn't the most obvious getting started doc? 😱

mcsf · 2020-02-05T10:47:22Z

docs/contributors/getting-started.md

@@ -34,6 +34,13 @@ Once Docker is installed and running, run this script to install WordPress, and
 npm run env install
 ```

+You will then also have to build your local WordPress install by running


It's odd that you should have to do this. env install, or a related command, should be handling any such needs automatically, IIRC. For instance, running env update pulls the latest changes and builds anew. I wonder if anything regressed.

Yeah, the fact that Noah was running into the same problem seemed to indicate to me that something might've regressed...

Right, I originally figured out what command to run because I looked through the code and saw that it was supposed to be running the npm commands within the WordPress repo. So it is probably worth fixing in the script if we want to keep this package working!

mcsf · 2020-02-05T10:49:18Z

Can you point me to up-to-date instructions on how to run Gutenberg locally?

I think the simplest would be

cd gutenberg
npm i -g @wordpress/env
wp-env start

See #17724 for more on wp-env.

epiqueras · 2020-02-05T10:58:29Z

Also https://github.com/WordPress/gutenberg/blob/master/packages/env/README.md.

ockham · 2020-02-05T11:01:25Z

$ wp-env start
✖ .IOError: [Errno 13] Permission denied: '~/.nvm/versions/node/v12.14.0/lib/node_modules/@wordpress/env/lib/docker-compose.yml'

😕

ockham · 2020-02-05T11:02:22Z

Gonna try npx instead, as suggested in the doc that Enrique linked.

epiqueras · 2020-02-05T11:03:43Z

It writes a file in node_modules and it looks like your setup doesn't allow that.

That will change in an upcoming PR but you should still get it sorted as I think a lot of popular tools do the same right now.

ockham · 2020-02-05T11:06:47Z

npx wp-env start
✔ Started WordPress@master. (in 87s 449ms)

🎉

I'll keep this PR open, since I didn't see https://github.com/WordPress/gutenberg/blob/master/packages/env/README.md linked anywhere from the root level README, nor the trail I was describing. We can use it to properly update docs to point to the @wp/env README.

epiqueras · 2020-02-05T11:09:20Z

Yes, without a trail this time 😄

Also, see #20002.

ockham · 2020-02-06T07:53:56Z

docs/contributors/getting-started.md

 ```
-
-#### Alternative Method: Using an Existing Local WordPress Install


I removed the entire section since I wasn't how to fit this in the bigger picture anymore; I had to modify a lot of the commands in subsequent sections to use wp-env, which wouldn't work with the instructions in this section. Okay to retire the alternative method section?

wp-env does support this with the config file PR. We might want to mention it here.

Done in 743c26c :)

ockham · 2020-02-06T07:54:19Z

docs/contributors/getting-started.md


 #### Toggling Debug Systems

 WordPress comes with specific [debug systems](https://wordpress.org/support/article/debugging-in-wordpress/) designed to simplify the process as well as standardize code across core, plugins and themes. It is possible to use environment variables (`LOCAL_WP_DEBUG` and `LOCAL_SCRIPT_DEBUG`) to update a site's configuration constants located in `wp-config.php` file. Both flags can be disabled at any time by running the following command:

 Example on Linux/MacOS:
 ```
-LOCAL_SCRIPT_DEBUG=false LOCAL_WP_DEBUG=false npm run env install
+LOCAL_SCRIPT_DEBUG=false LOCAL_WP_DEBUG=false npx wp-env start


Does this work with wp-env?

No, you have to navigate to the installation and edit the wp-config.php file for now.

@noisysocks We could add support to the wp-env config file though, right?

Yes it's on my list of follow-up work once #20002 is merged! 🙂

Updated for now: 65f5ad0

ockham · 2020-02-06T07:54:59Z

Okay, updated the docs. Wasn't sure about a few sections and would appreciate a review @epiqueras @mcsf 😄

epiqueras · 2020-02-06T10:12:53Z

docs/contributors/getting-started.md

 ```
 By default, both flags will be set to `true`.

 #### Troubleshooting

-You might find yourself stuck on a screen stating that "you are running WordPress without JavaScript and CSS files". If you tried installing WordPress via `npm run env install`, it probably means that something went wrong during the process. To fix it, try removing the `/wordpress` folder and running `npm run env install` again.
+You might find yourself stuck on a screen stating that "you are running WordPress without JavaScript and CSS files". If you tried installing WordPress via `npx wp-env start`, it probably means that something went wrong during the process. To fix it, try removing the `/wordpress` folder and running `npm run env install` again.


This doesn't apply. See the wp-env docs for troubleshooting info.

ockham · 2020-02-10T08:42:49Z

Thanks for your notes @epiqueras! I rebased the PR and addressed your feedback -- this is ready for another look.

* Update main project README Update main project repository reamde with various updates that bring it current for now and down the line. First organized it into a more general getting started recognizing the three levels that people might be coming to the project: as a User, as a Devleoper, and as a Contributor For User - added links to the user documentation, support forums, and how to report an issue For Develoepr - added links to the developer documentation For Contributor - simplifed the contributor sections and links to the contributors guide I removed the links at the bottom since those are mostly dated from when the project was starting out and justifying itself. These links can be included elsewhere for background and context, and not necessary on the welcoming page. * Use capitalize Block Editor, rework sentence * Update plugin readme.txt * Restore Code is Potery * Titlecase title * Updated intro paragraphs * Update Gutenberg screenshot * Text edit - tone down the revolution * Apply suggestions from code review Thanks for the updates 👍 Co-Authored-By: Chris Van Patten <hello@chrisvanpatten.com> * Add link for Getting Started guide, from #20044 Co-authored-by: Chris Van Patten <hello@chrisvanpatten.com>

ockham added [Type] Developer Documentation Documentation for developers [Type] Build Tooling Issues or PRs related to build tooling labels Feb 5, 2020

ockham requested a review from gziolo February 5, 2020 08:32

ockham requested review from ajitbohra and chrisvanpatten as code owners February 5, 2020 08:32

ockham self-assigned this Feb 5, 2020

gziolo requested a review from epiqueras February 5, 2020 08:57

gziolo requested a review from mcsf February 5, 2020 08:58

mcsf reviewed Feb 5, 2020

View reviewed changes

ockham force-pushed the update/docs-with-wordpress-build-step branch from 4994f4f to 301c127 Compare February 6, 2020 07:48

ockham commented Feb 6, 2020

View reviewed changes

ockham changed the title ~~Docs: Add missing step to Getting Started docs~~ Getting Started Docs: Update to use wp-env Feb 6, 2020

epiqueras requested changes Feb 6, 2020

View reviewed changes

gziolo requested a review from mkaz February 7, 2020 12:54

ockham force-pushed the update/docs-with-wordpress-build-step branch from 5d48d1a to 116893b Compare February 10, 2020 08:09

Getting Started Docs: Update to use

83ef9cb

ockham force-pushed the update/docs-with-wordpress-build-step branch from 116893b to 83ef9cb Compare February 10, 2020 08:22

ockham added 2 commits February 10, 2020 14:37

Link to .wp-env.json to use local WP install

743c26c

Update note on debug systems

65f5ad0

ockham requested a review from epiqueras February 10, 2020 08:43

epiqueras approved these changes Feb 10, 2020

View reviewed changes

ockham merged commit e00f7b4 into master Feb 10, 2020

ockham deleted the update/docs-with-wordpress-build-step branch February 10, 2020 12:16

github-actions bot added this to the Gutenberg 7.5 milestone Feb 10, 2020

mkaz added a commit that referenced this pull request Feb 10, 2020

Add link for Getting Started guide, from #20044

3c669c7

ockham mentioned this pull request Feb 12, 2020

wp-env: No longer working on Linux #20180

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Getting Started Docs: Update to use `wp-env` #20044

Getting Started Docs: Update to use `wp-env` #20044

ockham commented Feb 5, 2020 •

edited

Loading

gziolo commented Feb 5, 2020

ockham commented Feb 5, 2020 •

edited

Loading

mcsf Feb 5, 2020

ockham Feb 5, 2020

noahtallen Feb 5, 2020

mcsf commented Feb 5, 2020

epiqueras commented Feb 5, 2020

ockham commented Feb 5, 2020

ockham commented Feb 5, 2020

epiqueras commented Feb 5, 2020

ockham commented Feb 5, 2020

epiqueras commented Feb 5, 2020

ockham Feb 6, 2020

epiqueras Feb 6, 2020

epiqueras Feb 6, 2020

ockham Feb 10, 2020

ockham Feb 6, 2020

epiqueras Feb 6, 2020

noisysocks Feb 7, 2020

ockham Feb 10, 2020

ockham commented Feb 6, 2020

epiqueras Feb 6, 2020

ockham commented Feb 10, 2020

		```

		#### Alternative Method: Using an Existing Local WordPress Install

Getting Started Docs: Update to use wp-env #20044

Getting Started Docs: Update to use wp-env #20044

Conversation

ockham commented Feb 5, 2020 • edited Loading

Description

How has this been tested?

Types of changes

Checklist:

gziolo commented Feb 5, 2020

ockham commented Feb 5, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mcsf commented Feb 5, 2020

epiqueras commented Feb 5, 2020

ockham commented Feb 5, 2020

ockham commented Feb 5, 2020

epiqueras commented Feb 5, 2020

ockham commented Feb 5, 2020

epiqueras commented Feb 5, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ockham commented Feb 6, 2020

Choose a reason for hiding this comment

ockham commented Feb 10, 2020

Getting Started Docs: Update to use `wp-env` #20044

Getting Started Docs: Update to use `wp-env` #20044

ockham commented Feb 5, 2020 •

edited

Loading

ockham commented Feb 5, 2020 •

edited

Loading