WordPress.org

Making WordPress.org

Opened 6 weeks ago

Last modified 23 hours ago

#5581 new task

Consolidating setup of local Dev environment documentation and testing instructions.

Reported by: paaljoachim Owned by:
Milestone: Priority: normal
Component: General Keywords:
Cc:

Description

There are several places that have the same kind of documentation for setting up a local dev environment. These exist in various degrees of completeness and quality. There is also a crossover of docs in regards to testing/contributing. It would be great to see if we can combine these efforts and create one central place for documentation for setting up a local dev environment + testing instructions.

Here is an example from the Block Editor Handbook:
https://developer.wordpress.org/block-editor/tutorials/devenv/#quick-start
+
Issue in relation to testing pull requests:
https://github.com/WordPress/gutenberg/issues/25202

Here is an example from a post on P2:
https://make.wordpress.org/core/2021/01/15/test-scrub-for-wordpress-5-7/

Core Handbook Getting Started
https://make.wordpress.org/core/handbook/tutorials/getting-started/#setting-up-a-local-server

https://github.com/WordPress/wordpress-develop


Documentation we can easily update showing methods for WordPress core and Gutenberg. A document for setting up a local dev environment, and a document for testing trac tickets as well as Gutenberg Github pull requests.

Having an easy to follow step by step hand holding method with some short explanations and some troubleshooting tips would be a huge help to people at various skill levels. Making it easy for developers and non developers to follow.

Change History (26)

This ticket was mentioned in Slack in #core by paaljoachim. View the logs.


6 weeks ago

This ticket was mentioned in Slack in #core by metalandcoffee. View the logs.


6 weeks ago

#3 @paaljoachim
5 weeks ago

To begin the road to consolidating a setup for core and Gutenberg I need to know how both are done. By writing the instructions for both in this ticket.

The following are instructions for setting up a Local WP dev environment as well as how to test Trac tickets and Github PR's.


Core instructions. Setting up a Local Dev Environment.

I have with help from @hellofromtonya updated the testing instructions for setting up a local WP dev environment + testing trac tickets.

Setting up a local Development Environment for WordPress core.
The following are the Mac and Linux instructions. Further below are Window instructions.

1: Open Terminal.
2: Install homebrew by pasting

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

You might be asked if you want to install the Xcode Command Line Tools. Confirm yes.

3: Install Git by typing: brew install git
4: Install Docker by downloading the app here:
https://www.docker.com/products/docker-desktop
Or in terminal install Docker by typing:

brew cask install docker

If that does not work type:

brew install cask docker

5: In terminal. Install Node by typing:

brew install node

6: Open the Docker app on your computer and ignore the welcome screen that tells you to create a container.

7: Clone the Github repository. Go to https://github.com/WordPress/wordpress-develop
Click the green button (Code) at the top of the repository. Copy the HTTPS URL. https://github.com/WordPress/wordpress-develop.git
In terminal type:

git clone https://github.com/WordPress/wordpress-develop.git

8: Go to the directory where you cloned the repo.
Type:

cd wordpress-develop

9: Now type these 4 commands.

9A.

npm install

9B.

npm run build:dev

9C.

npm run env:start

9D.

npm run env:install

10: You should now be able to access the development version of WordPress at http://localhost:8889/.
Login with using
username: admin
password: password
-
-
A video tutorial I made for showing how to setup a local WP dev environment for WordPress core.
https://youtu.be/iit57Sg2pkU


Testing a Trac ticket or a Github PR.

NB!
There are special testing instructions for testing the themes 2019, 2020 or 2021. See instructions further below.

Open terminal and go to

cd wordpress-develop

An example Trac ticket:
https://core.trac.wordpress.org/ticket/43890

Type:

npm run grunt patch:43890

Add the trac ticket number to be tested.
After inserting the command an option will show up to where one can select which patch to test. With the up and down arrows on your keyboard select the newest patch (diff).

Login to your local WordPress site: http://localhost:8889/ with
username: admin
password: password

Check the results of the patch.

Sometimes one might be asked to test a WordPress Develop Github PR.
Here is an example of what to type in terminal (change the pull number):

npm run grunt patch:https://github.com/WordPress/wordpress-develop/pull/957

Login to http://localhost:8889/ and see if the patch/Pull Request (PR) works.

When done testing, discard the patch/PR's code changes to restore the wordpress develop directory by typing:

git reset --hard

-
-
-

Testing the following themes: 2019, 2020 and 2021.

These themes have their own build process which needs to be run before core development is run.

Here is an example for testing the Twenty Twenty One theme.

  1. First go to (if you are not already in the directory.):
cd wordpress-develop

Add:

cd src/wp-content/themes/twentytwentyone

Example.

paaljoachimromdahl@Paals-MacBook-Pro wordpress-develop % cd src/wp-content/themes/twentytwentyone
paaljoachimromdahl@Paals-MacBook-Pro twentytwentyone %
  1. Inside the twentytwentyone directory.

2A. Type:

npm install

2B. Type:

npm run build

We now have run the build for the Twenty Twenty One theme. The theme needs to have the Sass styles compiled before running the wordpress-develop build.

  1. Go back to the wordpress-develop directory.

Type:

cd ~/wordpress-develop


  1. Inside wordpress-develop.

Type:

npm run build

Go back to the "Testing a Trac ticket or a Github PR." further above.

-
-
A video tutorial I made for showing how to test a trac ticket patch:
https://youtu.be/87lvITWERTs
-
-

Troubleshooting in relation to testing.

Close and reopen terminal. Test again.
When you open http://localhost:8889/ be sure to log out and do a hard refresh and then log back in again.

Patches that includes JavaScript (JS) files one will also need to run the following command after having applied the patch:

npm run build

or

npm run build:dev

It will update the development build. Hopefully the patch will now be testable.
If the JavaScript is still not working then run the command.

npm run dev

Log out of the dev site and do a hard refresh and log back in again.

Something might happen so that you need to apply the patch again. If you have some errors then reseting the testing environment might help. Use the command:

git reset --hard

If your not able to open http://localhost:8889/
Then you might need to start up the environment by typing:

npm run env:start

-
-

Uninstall instructions

1: Uninstall Homebrew.
In terminal type:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/uninstall.sh)"

Type y to confirm.
Type your password.

2A.
Uninstall Docker.
Open Docker and go to the Dashboard.
Click the bug icon button seen in the top blue bar.
Click the Uninstall button.
Then drag the Docker app to your trash can.

2B.
Skip uninstalling Docker.
(If you do not want to remove Docker. Then follow these steps.)
Uninstall WordPress developer environment
In terminal type:

npm run env:reset

This will uninstall the Docker image and all the virtual discs it creates.

3: Delete wordpress-develop
Open the user folder in the root the wordpress-develop folder is located. Select it and drag it to the trash can.

Resource:
https://github.com/Homebrew/install


Windows instructions

Replace the above Mac/Linux instructions 1 - 6 with the following:

1: Install Git from https://git-scm.com/download/win
2: Download Docker Desktop from: https://www.docker.com/products/docker-desktop
Click Ok to enable Hyper-V and the Container features. Follow the prompts.
3: Download and install Node.js and NPM LTS version from https://nodejs.org/en/ (they are bundled together in one installer)

4: Restart your computer after completing step 3 to ensure system settings are correctly applied.

Follow steps 7 and onward in the Mac/Linux instructions.

Uninstall Windows Instructions

1: Uninstall Docker
Go to the "Uninstall Program" screen and select to uninstall Docker.

2: Delete wordpress-develop
Locate the wordpress-develop folder and delete.

Resource: https://docs.docker.com/docker-for-windows/install/

NB! I plan on creating a Learn Lesson/Workshop.

Last edited 26 hours ago by paaljoachim (previous) (diff)

This ticket was mentioned in Slack in #core by paaljoachim. View the logs.


5 weeks ago

This ticket was mentioned in Slack in #core-editor by paaljoachim. View the logs.


5 weeks ago

This ticket was mentioned in Slack in #core by paaljoachim. View the logs.


5 weeks ago

This ticket was mentioned in Slack in #meta by tellyworth. View the logs.


5 weeks ago

#8 @Clorith
5 weeks ago

In the case of a Windows install, you would replace steps 1 through 6 with the following:

1: Install Git from https://git-scm.com/download/win
2: Download Docker Desktop from https://www.docker.com/get-started
3: Download and install Node.js and NPM from https://nodejs.org/en/ (they are bundled together in one installer)

4: Restart your computer after completing step 3 to ensure system settings are correctly applied.

Docker automatically starts with your machine once installed on Windows unless you configure it to do otherwise.

Removing them afterwards should be a familiar experience to Windows users, as you would visit your computers "uninstall programs" screen and just select them there and they will be gone.

This ticket was mentioned in Slack in #meta by paaljoachim. View the logs.


5 weeks ago

This ticket was mentioned in Slack in #core by paaljoachim. View the logs.


5 weeks ago

This ticket was mentioned in Slack in #core by paaljoachim. View the logs.


5 weeks ago

This ticket was mentioned in Slack in #core by monikarao. View the logs.


5 weeks ago

This ticket was mentioned in Slack in #core by paaljoachim. View the logs.


5 weeks ago

This ticket was mentioned in Slack in #core by paaljoachim. View the logs.


4 weeks ago

This ticket was mentioned in Slack in #core-editor by paaljoachim. View the logs.


4 weeks ago

This ticket was mentioned in Slack in #community-team by paaljoachim. View the logs.


4 weeks ago

This ticket was mentioned in Slack in #core by paaljoachim. View the logs.


4 weeks ago

This ticket was mentioned in Slack in #core-themes by paaljoachim. View the logs.


4 weeks ago

This ticket was mentioned in Slack in #core by paaljoachim. View the logs.


3 weeks ago

This ticket was mentioned in Slack in #community-team by paaljoachim. View the logs.


3 weeks ago

#21 @paaljoachim
3 weeks ago

Setting up a local WP development Environment using VVV - Vagrant.

Some links.
https://make.wordpress.org/core/handbook/tutorials/installing-a-local-server/installing-vvv/

https://github.com/WordPress/contributor-day-handbook/blob/master/*Start%20Here%20-%20General%20Guides/How%20to%20setup%20VVV.md

https://github.com/Varying-Vagrant-Vagrants/CD-USB-Generator

https://varyingvagrantvagrants.org/docs/en-US/slack/


@abhanonstopnewsuk @macgraphic @tom

Step by steps tutorial will be added in this comment.
I will do research and figure out the newest instructions for Mac and Windows and add them here. Then add instructions + video to Learn.

Last edited 3 weeks ago by paaljoachim (previous) (diff)

This ticket was mentioned in Slack in #core by hellofromtonya. View the logs.


3 weeks ago

This ticket was mentioned in Slack in #core by monikarao. View the logs.


3 weeks ago

This ticket was mentioned in Slack in #community-events by paaljoachim. View the logs.


6 days ago

This ticket was mentioned in Slack in #core-test by francina. View the logs.


30 hours ago

#26 @paaljoachim
23 hours ago

I went ahead and made a Gutenberg issue.
wp-env: Consolidating setup of the dev environment for Core and Gutenberg.
https://github.com/WordPress/gutenberg/issues/29448

I believe we need some adventurers to explore the way forward.

Note: See TracTickets for help on using tickets.