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.

Sign up for GitHub

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

Jump to bottom

Docs: Update getting started with code #30447

Merged
merged 4 commits into from
Apr 13, 2021
Merged

Docs: Update getting started with code #30447

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
a7ee061
Clarify getting started docs for beginners
Apr 1, 2021
2747e43
Merge remote-tracking branch 'upstream/trunk' into update/getting-sta…
Apr 1, 2021
0e21021
Make wp-env recommended; add Docker notes
obulat Apr 2, 2021
71b053a
Update Windows 10 Docker setup link
obulat Apr 3, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 44 additions & 17 deletions docs/contributors/code/getting-started-with-code-contribution.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,54 +2,84 @@

The following guide is for setting up your local environment to contribute to the Gutenberg project. There is significant overlap between an environment to contribute and an environment used to extend the WordPress block editor. You can review the [Development Environment tutorial](/docs/getting-started/tutorials/devenv/README.md) for additional setup information.

## Development Tools (Node)
## Prerequisites

- Node.js
Gutenberg is a JavaScript project and requires [Node.js](https://nodejs.org/). The project is built using the latest active LTS release of node, and the latest version of NPM. See the [LTS release schedule](https://github.com/nodejs/Release#release-schedule) for details.

We recommend using the [Node Version Manager](https://github.com/nvm-sh/nvm) (nvm) since it is the easiest way to install and manage node for macOS, Linux, and Windows 10 using WSL2. See [our Development Tools guide](/docs/getting-started/tutorials/devenv/README.md#development-tools) or the Nodejs site for additional installation instructions.

After installing Node, you can build Gutenberg by running the following from within the cloned repository:
- Git
Gutenberg is using git for source control. Make sure you have an updated version of git installed on your computer, as well as a GitHub account. You can read the [Git Workflow](/docs/contributors/code/git-workflow.md) to learn more about using git and GitHub with Gutenberg

- [Recommended] Docker Desktop
We recommend using the [wp-env package](/packages/env/README.md) for setting WordPress environment locally. You'll need to install Docker to use `wp-env`. See the [Development Environment tutorial for additional details](/docs/getting-started/tutorials/devenv/README.md).
> Note: To install Docker on Windows 10 Home Edition, follow the [install instructions from Docker for Windows with WSL2](https://docs.docker.com/docker-for-windows/wsl/).

As an alternative to Docker setup, you can use [Local by Flywheel](https://localbyflywheel.com/), [WampServer](http://www.wampserver.com/en/), or [MAMP](https://www.mamp.info/), or even use a remote server.

## Getting the Gutenberg code
Fork the Gutenberg repository, clone it to your computer and add the WordPress repository as upstream.

```bash
npm ci
npm run build
$ git clone https://github.com/YOUR_GITHUB_USERNAME/gutenberg.git
$ cd gutenberg
$ git remote add upstream https://github.com/WordPress/gutenberg.git
```

## Building Gutenberg as a plugin
Install the Gutenberg dependencies and build your code in development mode:

```bash
npm ci
npm run dev
```
> Note: The install scripts require [Python](https://www.python.org/) to be installed and in the path of the local system. This might be installed by default for your operating system, or require downloading and installing.

Once built, Gutenberg is ready to be used as a WordPress plugin!
There are two ways to build your code. While developing, you probably will want to use `npm run dev` to run continuous builds automatically as source files change. The dev build also includes additional warnings and errors to help troubleshoot while developing. Once you are happy with your changes, you can run `npm build` to create optimized production build.

`npm run build` creates a single build of the project once. While developing, you probably will want to use `npm run dev` to run continuous builds automatically as source files change. The dev build also includes additional warnings and errors to help troubleshoot while developing.
Once built, Gutenberg is ready to be used as a WordPress plugin!

## Local Environment
## Local WordPress Environment

If you are familiar with WordPress and already have an environment setup, use the above build as a standard WordPress plugin by putting the gutenberg directory in your wp-content/plugins/ directory.
To test a WordPress plugin, you need to have WordPress itself installed. If you already have a WordPress environment setup, use the above Gutenberg build as a standard WordPress plugin by putting the gutenberg directory in your wp-content/plugins/ directory.

If you do not have a local WordPress environment setup, follow the steps in the rest of this section to create one.

### Using wp-env to Install a Local Environment
### Using Docker and wp-env

The [wp-env package](/packages/env/README.md) was developed with the Gutenberg project as a quick way to create a standard WordPress environment using Docker. It is also published as the `@wordpress/env` npm package.

By default, `wp-env` can run in a plugin directory to create and run a WordPress environment, mounting and activating the plugin automatically. You can also configure `wp-env` to use existing installs, multiple plugins, or themes. See the [wp-env package](/packages/env/README.md#wp-envjson) for complete documentation.

If you don't already have it, you'll need to install Docker and Docker Compose in order to use `wp-env`. See the [Development Environment tutorial for additional details](/docs/getting-started/tutorials/devenv/README.md).

Once Docker is installed and running: To install WordPress, run the following from within the cloned gutenberg directory:
Make sure Docker is running, and start `wp-env` from within the gutenberg directory:

```bash
npm run wp-env start
```

> Note: `npm run` will use the version specified within the Gutenberg project, making sure you are running the latest wp-env version.
This script will create a Docker instance behind the scenes with the latest WordPress Docker image, and then will map the Gutenberg plugin code from your local copy to the environment as a Docker volume. This way, any changes you make to the code locally are reflected immediately in the WordPress instance.

> Note: `npm run` will use the `wp-env` / `WordPress`?? version specified within the Gutenberg project, making sure you are running the latest wp-env version.

To stop the running environment:

```bash
npm run wp-env stop
```

If everyting went well, you should see the following message in your terminal:
```bash
WordPress development site started at http://localhost:8888/
WordPress test site started at http://localhost:8889/
MySQL is listening on port 51220

✔ Done! (in 261s 898ms)
```
And if you open Docker dashboard by rightclicking the icon in the menu bar(on Mac) or system tray (on Linux and Windows) and selecting 'Dashboard', you will see that the script has downloaded some Docker Images, and is running a Docker Container with fully functional WordPress installation:
![Screenshot of the WordPress Docker Container Running](https://cldup.com/mt9cKES-YZ.png)
![Screenshot of the Downloaded Docker Images for WordPress Development Environment](https://cldup.com/bNpgaRSkcG.png)

To destroy the install completely:

```bash
Expand All @@ -58,20 +88,17 @@ npm run wp-env destroy

Explore the [package documentation](/packages/env/README.md) for additional commands.


#### Accessing the Local WordPress Install

The WordPress installation should now be available at `http://localhost:8888`

You can access the Dashboard at: `http://localhost:8888/wp-admin/` using **Username**: `admin`, **Password**: `password`. You'll notice the Gutenberg plugin installed and activated, this is your local build.

#### Troubleshooting

If you run into an issue, check the [troubleshooting section in `wp-env` documentation](/packages/env/README.md#troubleshooting-common-problems).

### Using Local or MAMP

You can also use [Local by Flywheel](https://localbyflywheel.com/), [WampServer](http://www.wampserver.com/en/), or [MAMP](https://www.mamp.info/) as alternative environments to run a local WordPress environment. To do so clone and install Gutenberg as a regular plugin in your installation by creating a symlink or copying the directory to the proper `wp-content/plugins` directory.
As an alternative to Docker and `wp-env`, you can also use [Local by Flywheel](https://localbyflywheel.com/), [WampServer](http://www.wampserver.com/en/), or [MAMP](https://www.mamp.info/) to run a local WordPress environment. To do so clone and install Gutenberg as a regular plugin in your installation by creating a symlink or copying the directory to the proper `wp-content/plugins` directory.

You will also need some extra configuration to be able to run the e2e tests.

Expand Down
3 changes: 1 addition & 2 deletions docs/contributors/code/git-workflow.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,10 @@
# Git Workflow

The Gutenberg project follows a standard pull request process for contributions. See GitHub's documentation for [additional details about pull requests](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests).

This documentation is intended to help you get started using git with Gutenberg. Git is a powerful source code management tool; to learn git deeply, check out the [Pro Git book](https://git-scm.com/book/en/v2) available free online under CC BY-NC-SA 3.0 license.

If you are unfamiliar with using git, it is worthwhile to explore and play with it. Try out the [git tutorial](https://git-scm.com/docs/gittutorial) as well as the [git user manual](https://git-scm.com/docs/user-manual) for help getting started.

The Gutenberg project follows a standard pull request process for contributions. See GitHub's documentation for [additional details about pull requests](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests).
## Overview

An overview of the process for contributors is:
Expand Down
30 changes: 13 additions & 17 deletions docs/getting-started/tutorials/devenv/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.37.2/install.sh | bash

Quit and restart terminal
Install the long-term support (lts) version of node.

```
nvm install --lts
```
Expand All @@ -30,26 +31,24 @@ nvm install --lts

First download, install, and start [Docker Desktop](https://www.docker.com/products/docker-desktop) following the instructions for your OS.

- Install WordPress environment tool
- Install WordPress environment tool

```
npm -g install @wordpress/env
```

Start the environment from an existing plugin or theme directory, or a new working directory:

```
wp-env start
```
```
wp-env start
```

You will have a full WordPress site installed, navigate to: http://localhost:8888/ using your browser, log in to the WordPress dashboard at http://localhost:8888/wp-admin/ using Username "admin" and Password "password", without the quotes.


**3. Code Editor**

You can use any text editor to write code. For example, [Visual Studio Code](https://code.visualstudio.com/) is a popular open-source editor. You can follow instructions on their site to install it for your OS.


## Node Development Tools

The tools needed for development are **Node** and **NPM**. **Nodejs** is a runtime environment that allows running JavaScript outside of the browser. NPM is the Node Package Manager, it is used for installing dependencies and running scripts. The script `npx` is also installed with Nodejs—this script is used to run packages not yet installed—we will use `npx` to bootstrap a block.
Expand Down Expand Up @@ -115,7 +114,7 @@ There are several ways to run WordPress locally on your own computer, or you cou

The WordPress [wp-env package](https://www.npmjs.com/package/@wordpress/env) lets you set up a local WordPress environment for building and testing plugins and themes, without any additional configuration.

The `wp-env` tool uses Docker to create a virtual machine to that runs the WordPress site. There are instructions available for installing Docker on [Windows 10 Pro](https://docs.docker.com/docker-for-windows/install/), [all other versions of Windows](https://docs.docker.com/toolbox/toolbox_install_windows/), [macOS](https://docs.docker.com/docker-for-mac/install/), and [Linux](https://docs.docker.com/v17.12/install/linux/docker-ce/ubuntu/#install-using-the-convenience-script). If using Ubuntu, see our additional notes for [help installing Docker on Ubuntu](/docs/getting-started/tutorials/devenv/docker-ubuntu.md).
The `wp-env` tool uses Docker to create a virtual machine to that runs the WordPress site. There are instructions available for installing Docker on [Windows 10 Pro](https://docs.docker.com/docker-for-windows/install/), [other versions of Windows 10](https://docs.docker.com/docker-for-windows/wsl/), [macOS](https://docs.docker.com/docker-for-mac/install/), and [Linux](https://docs.docker.com/v17.12/install/linux/docker-ce/ubuntu/#install-using-the-convenience-script). If using Ubuntu, see our additional notes for [help installing Docker on Ubuntu](/docs/getting-started/tutorials/devenv/docker-ubuntu.md).

After you have installed Docker, go ahead and install the `wp-env` tool. This command will install the tool globally, which means you can run it from any directory:

Expand Down Expand Up @@ -150,18 +149,16 @@ If you run `wp-env start` from a directory that is not a plugin or theme, a gene

You can use the `.wp-env.json` configuration file to create an environment that works with multiple plugins and/or themes. See the [@wordpress/env package for additional details](/packages/env/README.md#wp-envjson).


#### Troubleshooting

A common issue when running `wp-env` is `Error while running docker-compose command.`

- Check that Docker Desktop is started and running.
- Check Docker Desktop dashboard for logs, restart, or remove existing VMs.
- Check that Docker Desktop is started and running.
- Check Docker Desktop dashboard for logs, restart, or remove existing VMs.

If you see the error: `Host is already in use by another container`

- The container is already running, or another one is. You can stop an existing container running use `wp-env stop` from the directory you started it.

- The container is already running, or another one is. You can stop an existing container running use `wp-env stop` from the directory you started it.

### Alternative to Docker

Expand Down Expand Up @@ -189,29 +186,28 @@ Here are a few instructions if you need to start over, or want to remove what wa

### Local Environment

* If you just want to reset and clean the WordPress database:
- If you just want to reset and clean the WordPress database:

```
wp-env clean all
```

* To remove the local environment completely for a specific project:
- To remove the local environment completely for a specific project:

```
wp-env destroy
```

* To completely uninstall wp-env tool:
- To completely uninstall wp-env tool:

```
npm -g uninstall @wordpress/env
```

* To uninstall Docker, or Visual Studio Code use your OS method to remove packages. For example, on Windows run "Add or remove programs". You can additionally uninstall from the Docker Desktop app, click the bug icon at the top to switch to this Troubleshoot screen. Click Uninstall or remove.
- To uninstall Docker, or Visual Studio Code use your OS method to remove packages. For example, on Windows run "Add or remove programs". You can additionally uninstall from the Docker Desktop app, click the bug icon at the top to switch to this Troubleshoot screen. Click Uninstall or remove.

![Docker Troubleshoot Screenshot](https://developer.wordpress.org/files/2020/08/docker-uninstall-screen.png)


### Uninstall Node/NVM

To uninstall Node/NVM, delete the NVM directory, this is typically installed at `$HOME/.nvm`, delete using
Expand Down