Skip to content
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.

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

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

Merged
merged 3 commits into from Feb 10, 2020

Conversation

@ockham
Copy link
Contributor

ockham commented Feb 5, 2020

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/ :

image

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.
@ockham ockham requested a review from gziolo Feb 5, 2020
@ockham ockham requested review from ajitbohra and chrisvanpatten as code owners Feb 5, 2020
@ockham ockham self-assigned this Feb 5, 2020
@gziolo gziolo requested a review from epiqueras Feb 5, 2020
@gziolo

This comment has been minimized.

Copy link
Member

gziolo commented Feb 5, 2020

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

@gziolo gziolo requested a review from mcsf Feb 5, 2020
@ockham

This comment has been minimized.

Copy link
Contributor Author

ockham commented Feb 5, 2020

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? 😱

@@ -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

This comment has been minimized.

Copy link
@mcsf

mcsf Feb 5, 2020

Contributor

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.

This comment has been minimized.

Copy link
@ockham

ockham Feb 5, 2020

Author Contributor

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

This comment has been minimized.

Copy link
@noahtallen

noahtallen Feb 5, 2020

Contributor

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

This comment has been minimized.

Copy link
Contributor

mcsf commented Feb 5, 2020

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

This comment has been minimized.

@ockham

This comment has been minimized.

Copy link
Contributor Author

ockham commented Feb 5, 2020

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

😕

@ockham

This comment has been minimized.

Copy link
Contributor Author

ockham commented Feb 5, 2020

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

@epiqueras

This comment has been minimized.

Copy link
Contributor

epiqueras commented Feb 5, 2020

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

This comment has been minimized.

Copy link
Contributor Author

ockham commented Feb 5, 2020

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

This comment has been minimized.

Copy link
Contributor

epiqueras commented Feb 5, 2020

Yes, without a trail this time 😄

Also, see #20002.

@ockham ockham force-pushed the update/docs-with-wordpress-build-step branch from 4994f4f to 301c127 Feb 6, 2020
```

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

This comment has been minimized.

Copy link
@ockham

ockham Feb 6, 2020

Author Contributor

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?

This comment has been minimized.

Copy link
@epiqueras

epiqueras Feb 6, 2020

Contributor

👍

This comment has been minimized.

Copy link
@epiqueras

epiqueras Feb 6, 2020

Contributor

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

This comment has been minimized.

Copy link
@ockham

ockham Feb 10, 2020

Author Contributor

Done in 743c26c :)


#### 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

This comment has been minimized.

Copy link
@ockham

ockham Feb 6, 2020

Author Contributor

Does this work with wp-env?

This comment has been minimized.

Copy link
@epiqueras

epiqueras Feb 6, 2020

Contributor

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?

This comment has been minimized.

Copy link
@noisysocks

noisysocks Feb 7, 2020

Member

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

This comment has been minimized.

Copy link
@ockham

ockham Feb 10, 2020

Author Contributor

Updated for now: 65f5ad0

@ockham

This comment has been minimized.

Copy link
Contributor Author

ockham commented Feb 6, 2020

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

@ockham ockham changed the title Docs: Add missing step to Getting Started docs Getting Started Docs: Update to use `wp-env` Feb 6, 2020
```
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 comment has been minimized.

Copy link
@epiqueras

epiqueras Feb 6, 2020

Contributor

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

@gziolo gziolo requested a review from mkaz Feb 7, 2020
@ockham ockham force-pushed the update/docs-with-wordpress-build-step branch from 5d48d1a to 116893b Feb 10, 2020
@ockham ockham force-pushed the update/docs-with-wordpress-build-step branch from 116893b to 83ef9cb Feb 10, 2020
@ockham

This comment has been minimized.

Copy link
Contributor Author

ockham commented Feb 10, 2020

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

@ockham ockham requested a review from epiqueras Feb 10, 2020
@ockham ockham merged commit e00f7b4 into master Feb 10, 2020
2 checks passed
2 checks passed
pull-request-automation
Details
Travis CI - Pull Request Build Passed
Details
@ockham ockham deleted the update/docs-with-wordpress-build-step branch Feb 10, 2020
@github-actions 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
mkaz added a commit that referenced this pull request Feb 10, 2020
* 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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

6 participants
You can’t perform that action at this time.