Merge pull request #5 from WordPress/master

Update master branch from original repo.

docs/contributors/document.md

@@ -25,7 +25,7 @@ The Block Editor Handbook is a mix of markdown files in the `/docs/` directory o
 
 An automated job publishes the docs every 15 minutes to the [Block Editor Handbook site](https://developer.wordpress.org/block-editor/).
 
-See [the Git Workflow](/docs/contributors/git-workflow.md) documentation for how to use git to deploy changes using pull requests.
+See [the Git Workflow](/docs/contributors/git-workflow.md) documentation for how to use git to deploy changes using pull requests. Additionally, see the [video walk-through](https://wordpress.tv/2020/09/02/marcus-kazmierczak-contribute-developer-documentation-to-gutenberg/) and the accompanying [slides for contributing documentation to Gutenberg](https://mkaz.blog/wordpress/contribute-documentation-to-gutenberg/).
 
 ### Update a Document
 

docs/contributors/getting-started.md

@@ -1,69 +1,79 @@
 # Getting Started
 
-Gutenberg is built using the [latest active LTS release](https://github.com/nodejs/Release#release-schedule) of [Node.js](https://nodejs.org/en/), along with the latest version of [NPM](http://npmjs.com/).
+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 Enviornment tutorial](/docs/designers-developers/developers/tutorials/devenv/readme.md) for additional setup information.
 
-The easiest way to install and manage node and NPM (on macOS, Linux, or Windows 10 with the Linux Subsystem) is by using [nvm](https://github.com/creationix/nvm). Once nvm is installed, you can install the correct version of Node by running nvm install --latest-npm in the Gutenberg directory.
+## Development Tools (Node)
 
-> **Note:** If you find yourself needing to build older versions of Gutenberg, nvm makes that process easier too. Because Gutenberg's `.nvmrc` file is regularly updated to the current available LTS release, running `nvm install` on an older branch will install whichever LTS version was active at that time.
+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 verion of NPM. See the [LTS release schedule](https://github.com/nodejs/Release#release-schedule) for details.
 
-Once you have Node installed, run these scripts from within your local Gutenberg repository:
+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/designers-developers/developers/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:
 
-Note: The install scripts require [Python](https://www.python.org/) to be installed and in the path of the local system.
 
 ```bash
 npm install
 npm run build
 ```
 
-This will build Gutenberg, ready to be used as a WordPress plugin!
+> 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.
 
-`npm run build` is intended for one-off compilations of the project. If you're planning to do continued development in the source files, using `npm run dev` will most often be the better option. This will configure the build to avoid minifying the generated output, rebuild files automatically as they are changed in your working directory, and configure dependencies as running in a development environment so that useful warnings and errors are logged to your browser's developer console.
+Once built, Gutenberg is ready to be used as a WordPress plugin!
 
-If you don't have a local WordPress environment to load Gutenberg in, we can help get that up and running, too.
+`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.
 
 ## Local Environment
 
-### Step 1: Installing a Local 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.
+
+If you do not have a local WordPress environment setup, follow the steps in the rest of this section to create one.
 
-The quickest way to get up and running is to use the [`wp-env` command](/packages/env/README.md), that is developed within the Gutenberg source repository, and published as `@wordpress/env` to npm. By default, wp-env can install and run a local WordPress environment for you. It is also possible to configure it to use a pre-existing local WordPress installation, [see package documentation](/packages/env/README.md) for configuration details.
+### Using wp-env to Install a Local Environment
 
-If you don't already have it, you'll need to install Docker and Docker Compose in order to use `wp-env`.
+The [wp-env package](/packages/env/README.md) was developed with the Gutneberg project as a quick way to create a standard WordPress environment using Docker. It is also published as the `@wordpress/env` npm package.
 
-To install Docker, follow the instructions for [Windows 10 Pro](https://docs.docker.com/docker-for-windows/install/), [all other version of Windows](https://docs.docker.com/toolbox/toolbox_install_windows/), [macOS](https://docs.docker.com/docker-for-mac/install/), or [Linux](https://docs.docker.com/v17.12/install/linux/docker-ce/ubuntu/#install-using-the-convenience-script). If running Ubuntu, see these [extended instructions for help and troubleshooting](/docs/designers-developers/developers/tutorials/devenv/docker-ubuntu.md).
+By default, `wp-env` can run in a plugin direcotry to create and run a WordPress enviornment, 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.
 
-To install Docker Compose, [follow their instructions here](https://docs.docker.com/compose/install/), be sure to select your operating system for proper instructions.
+If you don't already have it, you'll need to install Docker and Docker Compose in order to use `wp-env`. See the [Developement Environment tutorial for additional details](/docs/designers-developers/developers/tutorials/devenv/readme.md).
 
-Once Docker is installed and running, run this script to install WordPress, and build your local environment:
+Once Docker is installed and running: To install WordPress, run the following from within the cloned gutenberg directory:
 
 ```bash
-# Note: prefixing with "npm run" will resolve npm from the local Gutenberg source code, rather than a global install which may be out of date.
 npm run wp-env start
 ```
 
-### Step 2: Accessing and Configuring the Local WordPress Install
+> Note: `npm run` will use the version specified within the Gutenberg project, making sure you are running the latest wp-env version.
 
-#### Accessing the Local WordPress Install
+To stop the running environment:
 
-The WordPress installation should now be available at `http://localhost:8888` (**Username**: `admin`, **Password**: `password`).
-If this port is in use, you can override it using the `WP_ENV_PORT` environment variable. For more information, consult the `wp-env` [README](https://github.com/WordPress/gutenberg/blob/master/packages/env/README.md).
+```bash
+npm run wp-env stop
+```
 
-To shut down this local WordPress instance run `npm run wp-env stop`. To start it back up again, run `npm run wp-env start` again.
+To destroy the install completely:
 
-#### Toggling Debug Systems
+```bash
+npm run wp-env destroy
+```
 
-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. In order to use with `wp-env,` you'll have to edit your local WordPress install's `wp-config.php`.
+Explore the [package documentation](/packages/env/README.md) for additional commands.
 
-#### Troubleshooting
 
-See the [relevant section in `wp-env` docs](https://github.com/WordPress/gutenberg/tree/master/packages/env#troubleshooting-common-problems).
+#### 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
 
-## Using MAMP
+If you run into an issue, check the [troubleshooting section in `wp-env` documentation](/packages/env/README.md#troubleshooting-common-problems).
 
-You can also develop with MAMP by cloning and installing Gutenberg as a regular plugin in a WP install, but it comes with its caveats and will require some extra configuration to be able to run the e2e tests.
+### Using Local or MAMP
 
-### E2E testing
+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.
 
-Ensure that Gutenberg's E2E-dedicated plugins are available in the WordPress installation's `plugins` directory. For this, you can either copy the plugins as a whole, or you can create links from the Gutenberg project directory. This method is better in the long run but requires that link following be enabled. See section _Linking to other directories_ below, then come back and follow these instructions:
+You will also need some extra configuration to be able to run the e2e tests.
 
 Change the current directory to the plugins folder and symlink all e2e test plugins:
 
@@ -107,6 +117,9 @@ If so, you need to instruct Apache to allow following such links:
 - Add the following line: `Options +SymLinksIfOwnerMatch`
 
 ## On A Remote Server
+=======
+### On A Remote Server
+>>>>>>> Docs: Refresh Getting Started guide
 
 You can use a remote server in development by building locally and then uploading the built files as a plugin to the remote server.
 
@@ -150,14 +163,14 @@ With the extension installed, ESLint will use the [.eslintrc.js](https://github.
 
 [Prettier](https://prettier.io/) is a tool that allows you to define an opinionated format, and automate fixing the code to match that format. Prettier and ESlint are similar, Prettier is more about formatting and style, while ESlint is for detecting coding errors.
 
-To use Prettier with Visual Studio Code, you should install the [Prettier - Code formatter extension](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode). You can then configure it to be the default formatter and to automatically fix issues on save, by adding the following to your settings.
+To use Prettier with Visual Studio Code, you should install the [Prettier - Code formatter extension](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode). You can then configure it to be the default formatter and to automatically fix issues on save, by adding the following to your settings. __**Note**: depending on where you are viewing htis document, the brackets may show as double, the proper format is just a single bracket.__
 
 ```json
-"\[javascript\]": {
+"[[javascript]]": {
     "editor.defaultFormatter": "esbenp.prettier-vscode",
     "editor.formatOnSave": true
 },
-"\[markdown\]": {
+"[[markdown]]": {
     "editor.defaultFormatter": "esbenp.prettier-vscode",
     "editor.formatOnSave": true
 },

docs/contributors/git-workflow.md

@@ -1,26 +1,94 @@
 # Git Workflow
 
-A good workflow for new contributors to follow is listed below:
+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.
+
+## Overview
+
+An overview of the process for contributors is:
+
 - Fork the Gutenberg repository.
 - Clone the forked repository.
 - Create a new branch.
 - Make code changes.
+- Confirm tests pass.
 - Commit the code changes within the newly created branch.
 - Push the branch to the forked repository.
-- Submit a Pull Request to the Gutenberg repository.
+- Submit a pull request to the Gutenberg repository.
+
+See the [repository management document](/docs/contributors/repository-management.md) for additional information on how the Gutenberg project uses GitHub.
+
+## Git Workflow Walkthrough
+
+The workflow for code and documentation is the same, since both are managed in GitHub. You can watch a [video walk-through of contributing documentation](https://wordpress.tv/2020/09/02/marcus-kazmierczak-contribute-developer-documentation-to-gutenberg/) and the accompanying [slides for contributing to Gutenberg](https://mkaz.blog/wordpress/contribute-documentation-to-gutenberg/).
+
+
+Here is a visual overview of the Git workflow:
+
+![Visual Overview of Git Workflow](https://developer.wordpress.org/files/2020/09/git-workflow.png)
+
+
+**Step 1**: Go to the Gutenberg repository on GitHub and click Fork. This creates a copy of the main Gutenberg repository to your account.
+
+![Screenshot showing fork button on GitHub](https://developer.wordpress.org/files/2020/09/gutenberg-fork.png)
+
+**Step 2**: Clone your forked repository locally. It is located at: `https://github.com/YOUR-USER-NAME/gutenberg`. Cloning copies all the files to your computer. Open a terminal and run:
+
+```bash
+git clone https://github.com/YOUR-USER-NAME/gutenberg
+```
+
+This will create a directory called `gutenberg` with all the files for the project. It might take a couple of minutes because it is downloading the entire history of the Gutenberg project.
+
+**Step 3**: Create a branch for your change (see below for branch naming). For this example, the branch name is the complete string: `update/my-branch`
+
+```bash
+git switch -c update/my-branch
+```
 
-Ideally name your branches with prefixes and descriptions, like this: `[type]/[change]`. A good prefix would be:
+**Step 4**: Make the code changes. Build, confirm, and test your change thoroughly. See [coding guidelines](/docs/contributors/coding-guidelines.md) and [testing overview](/docs/contributors/testing-overview.md) for guidance.
+
+**Step 5**: Commit your change with a [good commmit message](https://make.wordpress.org/core/handbook/best-practices/commit-messages/). This will commit your change to your local copy of the repository.
+
+```bash
+git commit -m "Your Good Commit Message" path/to/FILE
+```
+
+**Step 6**: Push your change up to GitHub. The change will be pushed to your fork of the repository on the GitHub
+
+```bash
+git push -u origin upgrade/my-branch
+```
+
+**Step 7**: Go to your forked repository on GitHub -- it will automatically detect the change and give you a link to create a pull request.
+
+![Screenshot showing pull request link](https://developer.wordpress.org/files/2020/09/pull-request-create.png)
+
+**Step 8**: Create the pull request. This will create the request on the WordPress Gutenberg repository to integrate the change from your forked repository.
+
+**Step 9**: Keep up with new activity on the pull request. If any additional changes or updates are requested, then make the changes locally and push them up, following Steps 4-6.
+
+Do not make a new pull request for updates; by pushing your change to your respotiroy it will update the same PR. In this sense, the PR is a pointer on the WordPress Gutenberg repository to your copy. So when you update your copy, the PR is also updated.
+
+That’s it! Once approved and merged, your change will be incorporated into the main repository. 🎉
+
+
+## Branch Naming
+
+You should name your branches using a prefixes and short description, like this: `[type]/[change]`.
+
+Suggested prefixes:
 
 - `add/` = add a new feature
 - `try/` = experimental feature, "tentatively add"
 - `update/` = update an existing feature
+- `remove/` = remove an existing feature
 
 For example, `add/gallery-block` means you're working on adding a new gallery block.
 
-You can pick among all the <a href="https://github.com/WordPress/gutenberg/issues">tickets</a>, or some of the ones labelled <a href="https://github.com/WordPress/gutenberg/labels/Good%20First%20Issue">Good First Issue</a>.
-
-The workflow is documented in greater detail in the [repository management](/docs/contributors/repository-management.md) document.
-
 ## Keeping Your Branch Up To Date
 
 When many different people are working on a project simultaneously, pull requests can go stale quickly. A "stale" pull request is one that is no longer up to date with the main line of development, and it needs to be updated before it can be merged into the project.
@@ -69,8 +137,3 @@ git push
 ```
 
 The above commands will update your `master` branch from _upstream_. To update any other branch replace `master` with the respective branch name.
-
-
-## References
-- https://git-scm.com/book/en/v2
-- https://help.github.com/categories/collaborating-with-issues-and-pull-requests/