WordPress.org

Making WordPress.org

Opened 4 months ago

Last modified 2 days 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 (32)

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


4 months ago

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


4 months ago

#3 @paaljoachim
3 months 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 2 months ago by paaljoachim (previous) (diff)

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


3 months ago

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


3 months ago

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


3 months ago

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


3 months ago

#8 @Clorith
3 months 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.


3 months ago

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


3 months ago

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


3 months ago

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


3 months ago

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


3 months ago

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


3 months ago

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


3 months ago

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


3 months ago

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


3 months ago

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


3 months ago

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


3 months ago

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


3 months ago

#21 @paaljoachim
3 months 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.


I have been following this tutorial:
How to Set Up VVV for Contributing to WordPress.
https://github.com/WordPress/contributor-day-handbook/blob/master/*Start%20Here%20-%20General%20Guides/How%20to%20setup%20VVV.md

Here are some shorter instructions.

VVV (Varying Vagrant Vagrants) is a virtual machine that runs on Virtualbox. In other words, it is a self-contained local development environment aimed at WordPress developers. It can be used to build sites and contribute to the development of WordPress Core.

Mac, Linux and Windows instructions.

1- Installing VVV

Install VirtualBox: https://www.virtualbox.org/wiki/Downloads
Install Vagrant: https://www.vagrantup.com/downloads
Reboot your computer.

VVV Installation instructions: https://varyingvagrantvagrants.org/docs/en-US/installation/

Quick start instructions for installing VVV.
Cloning the main VVV repo into a local directory. In terminal, add:

git clone -b stable git://github.com/Varying-Vagrant-Vagrants/VVV.git ~/vagrant-local

The VVV repo will now be added to the new directory vagrant-local. Located in your operating system user root folder.

2- Start up VVV

Restart terminal then add

cd vagrant-local

Install local vagrant plugins if you have not already done so, add:

vagrant plugin install —-local

Start the Vagrant environment add this command:

vagrant up

You might need to add your operating system administrator password to properly modify the hosts file on your local machine. (When the prompt is seen type your password and click the enter/return key.)

Visit the VVV dashboard at http://vvv.test in your browser. You should see a listing of all the sites VVV created, as well as links to other administration-related tools.

VVV also includes the following two (disabled) environments.
-http://trunk.wordpress.test/ An SVN-based WordPress core trunk setup, useful for Contributor Days, Trac tickets, patches, general core contributing, etc.
-http://wp-meta.test A collection of sites for contributing to WordPress.org.

To enable wordpress-trunk (and wordpress-meta-environment).
To enable these environments, check if you have a config/config.yml file in your vagrant-local folder. If you do not have a config.yml file, then run vagrant status and it will be created for you.
In config.yml, look for the wordpress-trunk (and wordpress-meta-environment) and change skip_provisioning: true to skip_provisioning: false and save.

Back in terminal, add:

vagrant up --provision

to apply the change.

This will take some time to run, especially if you have enabled the Meta environment.

Go back to: http://vvv.test/
Notice the wordpress-trunk and wordpress-meta-environment are now active along with one.wordpress.test and two.wordpress.test.

Go to http://trunk.wordpress.test/ and login at
http://trunk.wordpress.test/wp-login.php
using these credentials:
admin
password

In terminal.
Add (if you are in the vagrant-local directory then skip to the next step):

cd vagrant-local

This opens the vagrant-local directory/folder inside the user root folder.

Add:

vagrant ssh

A pixelated waving bear will be seen.

Add:

cd /srv/www/wordpress-trunk/public_html

This enters the public_html folder inside wordpress-trunk which is inside the www folder. We need to use wordpress-trunk to test Trac patches and Github PRs.

Find a trac ticket with a patch.

I tried this one: https://core.trac.wordpress.org/ticket/39004
Used this command:

npm run grunt patch:39004

Uninstall

Uninstalling VVV VM (Virtual Machine)
In terminal go to the vagrant folder. Add:

cd vagrant-local

Then add:

vagrant destroy

Follow the prompts.

Delete the vagrant-local folder inside the OS root user folder.

Uninstalling Vagrant

Windows: Uninstall using the add/remove programs section of the control panel.
Mac: In terminal add:

sudo rm -rf /opt/vagrant /usr/local/bin/vagrant

Insert your OS password.

Then add:

sudo pkgutil --forget com.vagrant.vagrant

Linux: In terminal add:

rm -rf /opt/vagrant

then add:

rm -f /usr/bin/vagrant

Uninstalling VirtualBox

Windows: Go to Add/Remove Programs. Uninstall Virtualbox.
Linux: In terminal add:

sudo apt-get purge virtualbox*

I also saw this in the user manual:
Uninstallation of Oracle VM VirtualBox on Oracle Solaris requires root permissions. To perform the uninstallation, start a root terminal session and run the following command:

pkgrm SUNWvbox

After confirmation, this will remove Oracle VM VirtualBox from your system.

Mac:
Download the installer: https://www.virtualbox.org/ and mount.
Double click the VirtualBox_Uninstall.tool (One needs to go to Preferences -> Security & Privacy -> General and accept to open the tool.)
Follow the prompts.
Uninstall also FUSE????
When it is done it will say: [Process completed]

Resources:
https://www.vagrantup.com/docs/installation/uninstallation

https://technical-tips.com/blog/software/virtualbox-uninstall-completely--how-21709
https://osxdaily.com/2019/01/25/uninstall-virtualbox-mac-completely/
VirtualBox manual.

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

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


3 months ago

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


3 months ago

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


3 months ago

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


2 months ago

#26 @paaljoachim
2 months 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.

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


7 weeks ago

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


7 weeks ago

This ticket was mentioned in Slack in #accessibility 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-test by boniu91. View the logs.


3 days ago

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


2 days ago

Note: See TracTickets for help on using tickets.