Docs: How to pull a Gutenberg PR to your local WP develop environment setup.

[paaljoachim]

----The following issue is being worked on...---

I am first adding this issue with steps that @noahtallen shared with me.
I am first creating the issue, and will then very soon create the PR documentation.

Having documentation on how to run a Gutenberg PR will help make it possible for additional people to test the PR's and be able to give feedback as a feature is being built. Gutenberg.run is not reliable and we need a reliable way to test PR's.

There is a prerequisite one will need to do before following the below Quick Guide.
Go to the documentation for setting up a
Local WP Development Environment.
In the above documentation we set up the needed JavaScript tools and create a local WordPress development site.

---

Quick Guide

The first question you should ask yourself is.
Are you planning on only running PR's or do you think you might also contribute a PR to Gutenberg?

-1A- For running and optionally submitting PR's.
First we need to create a fork of the Gutenberg Github repository.
Go to: https://github.com/WordPress/gutenberg
Click the Fork button in the top right area of the screen. This creates a clone of the WordPress Gutenberg repository to your own Github account.

Open terminal and run: git clone https://github.com/YOUR-USER-NAME/gutenberg
Change YOUR-USER-NAME to your own Github repo account name.
This clones (downloads) the gutenberg repository locally to a gutenberg folder on you computer.
Go to step 2.

-1B- For only running Gutenberg PR's locally.
First we need to download the Gutenberg Github repository.
Go to: https://github.com/WordPress/gutenberg

Click the green Code button.
Click "Use HTTPS" text link.
Click the copy link icon containing this link: https://github.com/WordPress/gutenberg.git

Open terminal it will be in the root. (If you want to switch to another folder then add: cd nameoffolder.)
Add the following:
git clone https://github.com/WordPress/gutenberg.git

This will clone Gutenberg into the folder that is currently selected. I am in the root folder.
This is what I looked like in terminal on my Mac.

paaljoachimromdahl@Paals-MacBook-Pro ~ % git clone https://github.com/WordPress/gutenberg.git
Cloning into 'gutenberg'...
remote: Enumerating objects: 124, done.
remote: Counting objects: 100% (124/124), done.
remote: Compressing objects: 100% (105/105), done.
remote: Total 259637 (delta 56), reused 44 (delta 16), pack-reused 259513
Receiving objects: 100% (259637/259637), 1.07 GiB | 1.79 MiB/s, done.
Resolving deltas: 100% (183788/183788), done.
paaljoachimromdahl@Paals-MacBook-Pro ~ % 

If you want the Gutenberg folder in another directory, then you need to use the command cd nameofdirectory/folder and switch to that before cloning gutenberg.
Go to step 2.

-2-
In terminal. Add cd gutenberg to go to the newly downloaded Gutenberg folder.

-3-
Now we need to find the PR that we would like to run.
Here is an example of a Gutenberg PR I want to test:
#24419

I click the clipboard icon next to where it says update/list-view-design, and the following is copied:
update/list-view-design

In terminal I add:
git checkout update/list-view-design

This will copy the branch (PR) to our local version of gutenberg.

Result:

paaljoachimromdahl@Paals-MacBook-Pro ~ % cd gutenberg
paaljoachimromdahl@Paals-MacBook-Pro gutenberg % git checkout update/list-view-design
Branch 'update/list-view-design' set up to track remote branch 'update/list-view-design' from 'origin'.
Switched to a new branch 'update/list-view-design'
paaljoachimromdahl@Paals-MacBook-Pro gutenberg % 

-4-
We now need to run npm install from inside the gutenberg directory. It will install all of the project’s/Gutenberg(?) dependencies.
In terminal add: npm install

-5-
We now need to run npm run build in order to generate a production-ready build of the Gutenberg plugin. In terminal add: npm run build

NB!
-6-
In the prerequisite documentation for Setting up a Local WP development environment we started wp-env in the root folder. We now need to stop wp-env in the root as we are now working in the gutenberg folder.
In terminal add: cd ~/ which brings us back to the root folder. Then in terminal add: wp-env stop
Go back to the gutenberg folder by adding: cd gutenberg.

-7-
The following will start a wp-env instance within the Gutenberg folder.
In terminal add: npx wp-env start

It downloads WordPress.
Now test run a PR you have added above. In your browser click this link: http://localhost:8888/
It will open your local WP development environment site.
User name: admin and password: password

To test another Pull Request (PR)

-1- NB. Can probably be skipped if you have recently run other PR's.
Run: git pull to make sure all the latest changes from Github is available locally.

NEEDED -2-
Run: git checkout $branchname (change branchname to the correct name of the PR you are testing) will change the code files on your computer to be the ones in the other branch.

NEEDED -3-
Run: npm run build will build those files. Sometimes we need to run npm install first if the dependencies have changed.

-4- (Just refresh: http://localhost:8888/ and it should work fine. No need to restart npx wp-env start.)
Start up again localhost at http://localhost:8888/ and add in terminal:
npx wp-env start
Then check the PR you are running.

Uninstall

-1-
In terminal go to to the gutenberg folder cd gutenberg directory and add: npx wp-env destroy. That destroys the WordPress environment and data that was installed inside the gutenberg folder.

-2-
Outside of terminal. Locate the gutenberg folder inside the root user folder. Then delete the gutenberg folder.

[paaljoachim]

I received the following error when I tried to test another PR.

I had restarted terminal. I then switched to cd gutenberg. Then did a
git pull, then git checkout git checkout update/navigation-editor-redesign and received this terminal message:

error: Your local changes to the following files would be overwritten by checkout:
	package-lock.json
Please commit your changes or stash them before you switch branches.
Aborting
paaljoachimromdahl@Paals-MacBook-Pro gutenberg %  

Run: npm ci
Then: git reset --hard

The above should remove the package lock.

[paaljoachim]

npm install = updates NPM. Which is needed on occasion. Especially if some error messages show up.

git reset --hard 5aef47571ce2bc6cfae8bb17d2fe721b758ecf15 (resets to the commit number you add. To make sure that the correct commit number is being tested.)

npm ci = installs the dependencies without updating.

git reset --hard = permanently undoes all changes to local files and makes the files match exactly what is in the branch. This is most useful when you have unintentional changes.

git stash = moves any local changes into a “stash” so that they aren’t visible, but you can still get them back at a later time. This would be useful if you made an intentional change locally, but wanted to switch to a branch to test something else out.

git status = mentions any local changes.

git checkout = changes the files on the computer to match what the contributor has written in their branch.

npm run build = takes whatever files are on the computer, and turns them into the final plugin to run in WordPress.

wp-env start --update = Restarts wp env and also updates it.

npx wp-env = will reference the wp-env code which lives inside the current repository. So in the case of gutenberg, it will reference the latest source code for the command.

wp-env = accesses the globally installed code, which comes from NPM.

Example go to cd gutenberg = go to the gutenberg folder.

cd ~/ = Go to the root user folder.

[paaljoachim]

Questions that come up....

I noticed in the Dashboard in Docker. (On a Mac) top right bar to the left of the wifi icon is the Docker icon (if it has been started up that is). In the drop down is the option to select Dashboard. One sees a stack. Clicks the orange icon/area. Enters the containers screen. Here one can also click Port:8888 to access the localhost 8888 web site. There is also a port 8889.
Noah said: The difference is that 8888 uses one database, and 8889 uses a different database. 8888 is for normal development purposes and use, and 8889 is for any automated test data

[noahtallen]

Since we have already started wp-env in the root folder through the prerequisite, we now need to stop wp-env there. In terminal add: cd ~/ which brings us back to the root folder. Then in terminal add: wp-env stop

Theoretically, we could add a note to the prerequisite so that folks don't start wp-env from the root directory if they are going to use it with a plugin

[paaljoachim]

We can talk more about it Noah, and see if that is the logical approach.

---

An example use case.

NB. First follow 1B above: #25202 (comment)
By downloading the Gutenberg Github repository.
Go to: https://github.com/WordPress/gutenberg
Open terminal it will be in the root. (If you want to switch to another folder then add: cd nameoffolder.)
Add the following:
git clone https://github.com/WordPress/gutenberg.git

I want to test this PR. #24875
The new Navigation PR which is being worked on.

I copy the needed information: update/navigation-editor-redesign

I reopen terminal.
Switch to the gutenberg folder.
cd gutenberg

Add:
git pull to get the newest PR updates.
git checkout update/navigation-editor-redesign select the PR to run.
npm run buildruns the newest build of the PR.

Open Docker. As Docker needs to be open before starting up the local version of WordPress.

Add (optional if this has recently been started.):
npx wp-env start to Startup WordPress.

Then either through Docker -> Dashboard -> Stack -> hover over a Container which mentions the port:888 and click the icon to open the browser.
Or just go directly to http://localhost:8888/
User: admin. Password: password

There was an error in the top of the wp-admin but I just skipped it and went straight to the Navigation beta screen, and could see the latest build.

[noahtallen]

Yep, those steps make sense to me! npx wp-env start is optional if you have already started it recently. So it doesn't really do anything if you run it again there while it is already running. But it doesn't hurt either :)

[paaljoachim]

### ---- Will be edited. Please DM me adjustments that I can add below. Thank you!-----
Hopefully this is the method that is most used by developers, and is the method that should be added to the Block Editor handbook. Shared by @ntsekouras

An improved method of running a PR and/or contributing to Gutenberg.

Using remotes.
https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes
(I will add an explanation of what a remote is.)

When the user has access rights to the Gutenberg repo. To get access rights one needs to ask in the Slack Core Editor channel to be added to the team.

For running a PR or contributing this step needs to be done. Add to terminal:

1. Duplicate the gutenberg repo locally to your own computer.
   git clone https://github.com/WordPress/gutenberg.git

How to run (test) a PR when user has access, as part of the Gutenberg team.
More correct would be: How to run (test) a PR when the base branch is a fork. Hmm I need to say this simpler or atleast add in an explanation.

To figure out if the PR you are running is from a user who has access then look at the PR and see if it says from example username. from talldan:fix/some-bug or if the username is not mentioned: from fix/some-bug
(The above needs editing...)

Add the following commands to terminal:

2a. Add the remote from that users fork. I am using the example with ntsekuras username, but I can call it anything that I want. The username in the URL needs to be correct.
git remote add ntsekouras https://github.com/username/gutenberg.git

3a. Get branches/work done on this users remote repo. I can rename ntsekouras to anything that I choose.
git fetch ntsekouras

4a. Get the PR that is to run. I can rename ntsekouras to anything that I choose.
git checkout ntsekouras/fix/something-to-fix

5a. NPM needs to be installed.
npm install

6a. Run the current npm build.
npm run build

7a. Start the local WP dev environment to gain access to http://localhost:8888/
npx wp-env start

To contribute when the user has access, as part of the Gutenberg team.

1. Step is seen above. Clone the gutenberg repo.

2b. Create a new local branch to work on git checkout -b fix/something-to-fix-here fix/update/etc.
3b. Then to push the changes to your forked Gutenberg repo:
git remote add upstream https://github.com/WordPress/gutenberg.git
4b. Then go to the official gutenberg repo and create a new Pull Request.
5b. Instructions on how to create a Pull Request --> will be added.

---

When the user does NOT have access rights to the Gutenberg repo. To get access rights one needs to ask in the Slack Core Editor channel to be added to the team.

How to run a PR when user does not have access to the Gutenberg team.

How to contribute when user does not have access to the Gutenberg team

1. Fork - create a duplicate of the Gutenberg repo.
   git clone https://github.com/YOUR-USER-NAME/gutenberg.git

2. Create a new local branch to work on
   git checkout -b fix/something-to-fix-here
   More info to show up here in relation to various kinds: fix/update/etc.

3. Push the changes to your fork of the Gutenberg repo:
   git remote add upstream https://github.com/WordPress/gutenberg.git

4. Then go to the Gutenberg repo and create a new Pull Request.
   Instructions to follow.

A think thank you to @ntsekouras for the above instructions!

[paaljoachim]

Here is an even simpler way of running a PR. Shared by @talldan

https://stackoverflow.com/questions/27567846/how-can-i-check-out-a-github-pull-request-with-git

Here’s another one that’s a bit shorter, potentially easier, and should work with any PR (whether on a fork or not):

1. Clone the main git repository (if you haven’t already)
   git clone https://github.com/WordPress/gutenberg.git

2. Go to the gutenberg directory.
   cd gutenberg

3. Find the PR you want to test and note it’s number.
   Run the command git fetch origin pull/<number>/head replacing with the PR number

4. Switch to the ‘Commits’ tab for the PR in github and copy the reference for the most recent commit (bottom) using the copy button.
   Run the command git checkout <commit-ref> where is the reference you just copied

5. Run npm run build to build the code.

Example use case:
Testing this PR: #21859

1. git clone https://github.com/WordPress/gutenberg.git

(Optionally start: npx wp-env start)

2. Go to the gutenberg folder:
   cd gutenberg

3. git fetch origin pull/21859/head

Terminal result:

From https://github.com/WordPress/gutenberg
 * branch                  refs/pull/21859/head -> FETCH_HEAD

4. git checkout fdd36511834c109160bb28324bdd4400b66e1656
   (bottom commit.)

Terminal result:
HEAD is now at fdd3651183 Merge branch 'master' into update/flat-term-selector

5. npm run build

6. Go to: http://localhost:8888/
   Username: admin and Password: password
   Test run the PR.

EDIT: Update 21 October
NB! I have noticed that rechecking PRs that older commits might be seen instead of the one that is added. I had to add this command including the newest commit to make sure that I was checking the correct version:
git reset --hard <SOME-COMMIT>
Example: #25921 (comment)
I had to add git reset --hard 5aef47571ce2bc6cfae8bb17d2fe721b758ecf15
Found info here: https://stackoverflow.com/questions/9529078/how-do-i-use-git-reset-hard-head-to-revert-to-a-previous-commit

NB!
Sometimes the above approach will not work.
For instance I tried this PR earlier today using the above approach in testing a commit.
#26615

I had to instead use this approach:
git checkout update/add-full-height-alignment-toolbar
npm run build

That worked.

[paaljoachim]

I am thinking of using the information in this comment: #25202 (comment)
as well as the comment just above here as an alternative.

I will just have to focus on running (testing) a PR.

[aristath]

Just a note, the new Github CLI makes a lot of these tasts a lot easier...
On any PR now on the top right there is an "open with" button:

This of course requires actually installing the GH CLI first, but that's easy enough to do and their docs on how to install it are pretty good and cover all OSs

[bph]

Reasoning for removal of UserDocumentation label:
User documentation is meant to flag issues that need to be considered for Block Editor End User documentation.
End User = non-developer in this context. (See Editor Chat summary August 19, 2020 first open floor item)

[paaljoachim]

Right now I have a few methods for running/testing a PR. That are short and to the point. Ari I will wait a little bit with Github CLI. I need to land the how to contribute alongside the running of PR's.

As for running a PR one downloads the Gutenberg repo, and it seems for contributing one downloads a fork of the Gutenberg repo. For this approach one needs two folders locally containing the Gutenberg repo. I am thinking there needs to be a much simpler way of contributing in addition to using the above simple approaches to running a PR.

[paaljoachim]

An error guide... (EDITED: based on feedback from @talldan )

I received this error:

Did a search for code ELIFECYCLE and found this page: https://reactgo.com/npm-err-code-elifecycle/
Followed the instructions.
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

npm install can take a while to install. It will update packages to the right version on your local machine.

I restarted terminal switched to cd gutenberg folder. Restarted Docker. Then tested a PR.
(If needed start: npx wp-env start to start up again the local WP dev environment.)

---

Another type of error message.

If you get an message in terminal mentioning:

error: Your local changes to the following files would be overwritten by merge:
file/name/path
some/more/filenamepath
Please, commit your changes or stash them before you can merge.
Aborting

I have found that one way to switch branches/testing another PR is to first write:
git pull --rebase
As that seems to reset what is being tested.
This needs to be updated. As I just need to remove the old test branch and open the new test branch for testing.

[skorasaurus]

An error guide.

Did a search for code ELIFECYCLE and found this page: https://reactgo.com/npm-err-code-elifecycle/
Followed the instructions.
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

Restarted terminal. The error had gone away. Restarted Docker. Then tested/ran a PR.

Great work on this @paaljoachim

I understand that we shouldn't provide troubleshooting advice for every single use case in the docs but I've also found that npm advice (quoted above) is really helpful when encountering similar errors when testing out PRs and switching between branches, etc and should be included in the docs.

[talldan]

Agree with @skorasaurus on this. Just to give feedback on the errors:

Did a search for code ELIFECYCLE and found this page

The error message mentions node_modules missing, did you mean to install. I think you must have deleted the node_modules folder at some point and npm install will bring it back, so the instructions were partly right, but you most likely didn't need to carry out the first two steps ...

An option here is that we could add a nicer error message to npm run build to make it clearer to users what steps they need to take when the node_modules is missing. However I would say it's good practice to run npm install on a fairly regular basis anyway, so that might be something worth mentioning in documentation.

The reason for this is that npm install installs all the project dependencies. These dependencies change over time. For example, React might be upgraded to a more recent version. npm install updates packages to the right version on your local machine.

I have found that one way to switch branches/testing another PR is to first write:
git pull --rebase

This is tricky to answer without knowing exactly what happened. It happens when there are local changes to files within the project. git doesn't want to overwrite these changes as they might be something you want to keep (so this error is a bit like 'Are you sure? Don't you want to save your changes?'). This could happen if you made changes manually, but also sometimes happens for a number of other reasons 😓.

I don't think rebasing is the right thing to do, really you want to look at what changes have been made to the files and either get rid of them, stash them, or commit them. That SO thread is very misleading. 😬

[paaljoachim]

EDITED: Added corrections from Dan.

How to test a PR made by a non team member.
(Draft this comment needs to be adjusted.)

Non team members have their name added to the file(?).
For instance this Pull Request: #25791

aaronrobertshaw:try/border-radius-block-support

They add PRs to their own gutenberg fork. Meaning they use their own repository instead of directly the Gutenberg repository (This is entirely correct and needs to be adjusted.)

To be able to test a PR from a non team member the testing process is a little different.

#25791
Block Support: Add border radius support and use for search block

git remote -v (lists the remote connections)
git remote add aaron https://github.com/aaronrobertshaw/gutenberg.git
(Adds the name aaron as a new remote connection to his fork of gutenberg. It was my choice to call it aaron.)

git fetch aaron (Get branches from the aaron remote.)
git checkout try/border-radius-block-support (Branch - Finally tests out the PR he made.)

To remove a Git remote locally use:
git remote rm <remote-name>

Example.
git remote rm aaron

To check if a remote was removed, use
git remote -v

https://linuxize.com/post/how-to-remove-git-remotes/

[talldan]

(Adds the name aaron as a new local connection branch to his gutenberg fork. It was my choice to call it aaron.)

git fetch aaron (Gets aaron branch.)

A couple of corrections here that I think are worth making.

• (Adds the name aaron as a new 'remote' connection to his fork of gutenberg. It was my choice to call it aaron.)
• git fetch aaron (Get branches from the aaron remote.)

Happy to go into more detail if needed.

[aristath]

Though learning how to use git git is a good task to have, it should not necessarily be the purpose of our docs to teach people git. The goal is to show people how to test something as easily as humanly possible. So... why not just use the GitHub CLI? It's a single line to test a PR: gh pr checkout 25202 and you're done, no need to add remote connections, fetch them, checkout etc.

[paaljoachim]

Thank you Dan @talldan for the corrections! I have updated the text.

Ari @aristath as I get different methods of testing a PR in place, and use them myself. I also add adjustments along the way based on my own tests. It will be natural to also add how to test a PR with Github CLI.
This is so that people have different methods of testing a PR. Ending up with using Github CLI and finding out that it is the easiest method would be a fitting end after having gone through the more difficult approaches.

I will get back to both of you!
Thank your for helping me get this in place!

[alexstine]

@paaljoachim I forget if it was you or someone else, but I posted at some point that I would try these instructions out and never did. 3 months forward, here I am. I followed step by step what you wrote and successfully setup a local dev env on my Mac and was able to test a PR.

Thanks for the solid instructions. :)

[mtias]

@paaljoachim are there any followups here?

[paaljoachim]

Hey @mtias
Actually I should recheck the instructions and update if needed and add what is needed into the Block Editor Documentation.
I can probably get some help from @mkaz Marcus with this.

[mtias]

@paaljoachim is this still active?

[annezazu]

Came here to ask the same after it didn't work this week :)

[paaljoachim]

It seems like we need an update.

I have not tested this out in a while. I have been been using the Gutenberg PR build to test PR's. https://make.wordpress.org/design/2021/03/03/testing-a-gutenberg-pull-request-pr/

[noahtallen]

By the way, I've been using the gh CLI tool to test PRs from contributors without write access. Once installed, you just run gh pr checkout 12345 in the repository. There's no need to set up extra remotes or anything. You just give it the PR number and it does everything else :)

[mtias]

I'm closing this, but feel free to open a PR updating docs with anything that might be useful!