Merge branch 'master' into i18n-updates

.eslintrc.js

@@ -19,7 +19,7 @@ const majorMinorRegExp = escapeRegExp( version.replace( /\.\d+$/, '' ) ) + '(\\.
 module.exports = {
 	root: true,
 	extends: [
-		'@wordpress/eslint-config',
+		'plugin:@wordpress/eslint-plugin/recommended',
 		'plugin:jest/recommended',
 	],
 	rules: {

.github/PULL_REQUEST_TEMPLATE.md

@@ -19,3 +19,4 @@
 - [ ] My code follows the WordPress code style. <!-- Check code: `npm run lint`, Guidelines: https://make.wordpress.org/core/handbook/best-practices/coding-standards/javascript/ -->
 - [ ] My code follows the accessibility standards. <!-- Guidelines: https://make.wordpress.org/core/handbook/best-practices/coding-standards/accessibility-coding-standards/ -->
 - [ ] My code has proper inline documentation. <!-- Guidelines: https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/javascript/ -->
+- [ ] I've included developer documentation if appropriate. <!-- Handbook: https://wordpress.org/gutenberg/handbook/designers-developers/ -->

.travis.yml

@@ -58,7 +58,7 @@ jobs:
         - ./bin/run-wp-unit-tests.sh
 
     - stage: test
-      env: WP_VERSION=latest
+      env: WP_VERSION=latest POPULAR_PLUGINS=true
       script:
         - ./bin/run-e2e-tests.sh || exit 1
 

bin/install-wordpress.sh

@@ -45,41 +45,59 @@ echo ''
 # dirty up the tests.
 if [ "$1" == '--e2e_tests' ]; then
 	echo -e $(status_message "Resetting test database...")
-	docker-compose $DOCKER_COMPOSE_FILE_OPTIONS run --rm $CLI db reset --yes >/dev/null
+	docker-compose $DOCKER_COMPOSE_FILE_OPTIONS run --rm -u 33 $CLI db reset --yes --quiet
 fi
 
 # Install WordPress.
 echo -e $(status_message "Installing WordPress...")
 # The `-u 33` flag tells Docker to run the command as a particular user and
 # prevents permissions errors. See: https://github.com/WordPress/gutenberg/pull/8427#issuecomment-410232369
-docker-compose $DOCKER_COMPOSE_FILE_OPTIONS run --rm -u 33 $CLI core install --title="$SITE_TITLE" --admin_user=admin --admin_password=password --admin_email=test@test.com --skip-email --url=http://localhost:$HOST_PORT >/dev/null
+docker-compose $DOCKER_COMPOSE_FILE_OPTIONS run --rm -u 33 $CLI core install --title="$SITE_TITLE" --admin_user=admin --admin_password=password --admin_email=test@test.com --skip-email --url=http://localhost:$HOST_PORT --quiet
 
 if [ "$E2E_ROLE" = "author" ]; then
-	# Create an additional author user for testsing.
-	docker-compose $DOCKER_COMPOSE_FILE_OPTIONS run --rm -u 33 $CLI user create author author@example.com --role=author --user_pass=authpass
+	echo -e $(status_message "Creating an additional author user for testing...")
+	# Create an additional author user for testing.
+	docker-compose $DOCKER_COMPOSE_FILE_OPTIONS run --rm -u 33 $CLI user create author author@example.com --role=author --user_pass=authpass --quiet
 	# Assign the existing Hello World post to the author.
-	docker-compose $DOCKER_COMPOSE_FILE_OPTIONS run --rm -u 33 $CLI post update 1 --post_author=2 
+	docker-compose $DOCKER_COMPOSE_FILE_OPTIONS run --rm -u 33 $CLI post update 1 --post_author=2 --quiet
 fi
 
+# Make sure the uploads and upgrade folders exist and we have permissions to add files.
+echo -e $(status_message "Ensuring that files can be uploaded...")
+docker-compose $DOCKER_COMPOSE_FILE_OPTIONS run --rm $CONTAINER chmod 767 /var/www/html/wp-content/plugins
+docker-compose $DOCKER_COMPOSE_FILE_OPTIONS run --rm $CONTAINER mkdir -p /var/www/html/wp-content/uploads
+docker-compose $DOCKER_COMPOSE_FILE_OPTIONS run --rm $CONTAINER chmod -v 767 /var/www/html/wp-content/uploads
+docker-compose $DOCKER_COMPOSE_FILE_OPTIONS run --rm $CONTAINER mkdir -p /var/www/html/wp-content/upgrade
+docker-compose $DOCKER_COMPOSE_FILE_OPTIONS run --rm $CONTAINER chmod 767 /var/www/html/wp-content/upgrade
+
+CURRENT_WP_VERSION=$(docker-compose $DOCKER_COMPOSE_FILE_OPTIONS run -T --rm $CLI core version)
+echo -e $(status_message "Current WordPress version: $CURRENT_WP_VERSION...")
+
 if [ "$WP_VERSION" == "latest" ]; then
 	# Check for WordPress updates, to make sure we're running the very latest version.
-	docker-compose $DOCKER_COMPOSE_FILE_OPTIONS run --rm -u 33 $CLI core update >/dev/null
+	echo -e $(status_message "Updating WordPress to the latest version...")
+	docker-compose $DOCKER_COMPOSE_FILE_OPTIONS run --rm -u 33 $CLI core update --quiet
 fi
 
 # If the 'wordpress' volume wasn't during the down/up earlier, but the post port has changed, we need to update it.
+echo -e $(status_message "Checking the site's url...")
 CURRENT_URL=$(docker-compose $DOCKER_COMPOSE_FILE_OPTIONS run -T --rm $CLI option get siteurl)
 if [ "$CURRENT_URL" != "http://localhost:$HOST_PORT" ]; then
-	docker-compose $DOCKER_COMPOSE_FILE_OPTIONS run --rm $CLI option update home "http://localhost:$HOST_PORT" >/dev/null
-	docker-compose $DOCKER_COMPOSE_FILE_OPTIONS run --rm $CLI option update siteurl "http://localhost:$HOST_PORT" >/dev/null
+	docker-compose $DOCKER_COMPOSE_FILE_OPTIONS run --rm -u 33 $CLI option update home "http://localhost:$HOST_PORT" --quiet
+	docker-compose $DOCKER_COMPOSE_FILE_OPTIONS run --rm -u 33 $CLI option update siteurl "http://localhost:$HOST_PORT" --quiet
 fi
 
 # Activate Gutenberg.
 echo -e $(status_message "Activating Gutenberg...")
-docker-compose $DOCKER_COMPOSE_FILE_OPTIONS run --rm $CLI plugin activate gutenberg >/dev/null
+docker-compose $DOCKER_COMPOSE_FILE_OPTIONS run --rm -u 33 $CLI plugin activate gutenberg --quiet
 
-# Make sure the uploads folder exist and we have permissions to add files there.
-docker-compose $DOCKER_COMPOSE_FILE_OPTIONS run --rm $CONTAINER mkdir -p /var/www/html/wp-content/uploads
-docker-compose $DOCKER_COMPOSE_FILE_OPTIONS run --rm $CONTAINER chmod -v 767 /var/www/html/wp-content/uploads
+if [ "$POPULAR_PLUGINS" == "true" ]; then
+	echo -e $(status_message "Activating popular plugins...")
+	docker-compose $DOCKER_COMPOSE_FILE_OPTIONS run --rm -u 33 $CLI plugin install advanced-custom-fields --activate --quiet
+	docker-compose $DOCKER_COMPOSE_FILE_OPTIONS run --rm -u 33 $CLI plugin install jetpack --activate --quiet
+	docker-compose $DOCKER_COMPOSE_FILE_OPTIONS run --rm -u 33 $CLI plugin install wpforms-lite --activate --quiet
+fi
 
 # Install a dummy favicon to avoid 404 errors.
+echo -e $(status_message "Installing a dummy favicon...")
 docker-compose $DOCKER_COMPOSE_FILE_OPTIONS run --rm $CONTAINER touch /var/www/html/favicon.ico

docs/contributors/coding-guidelines.md

@@ -170,7 +170,7 @@ function MyComponent() {}
 
 An exception to camel case is made for constant values which are never intended to be reassigned or mutated. Such variables must use the [SCREAMING_SNAKE_CASE convention](https://en.wikipedia.org/wiki/Snake_case).
 
-In almost all cases, a constant should be defined in the top-most scope of a file. It is important to note that [JavaScript's `const` assignment](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/const) is conceptually more limited than what is implied here, where a value assigned by `const` in JavaScript can in-fact be mutated, and is only protected against reassignment. A constant as defined in these coding guidelines applies only to values which are expected to never change, and is a strategy for developers to communicate intent moreso than it is a technical restriction.
+In almost all cases, a constant should be defined in the top-most scope of a file. It is important to note that [JavaScript's `const` assignment](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/const) is conceptually more limited than what is implied here, where a value assigned by `const` in JavaScript can in-fact be mutated, and is only protected against reassignment. A constant as defined in these coding guidelines applies only to values which are expected to never change, and is a strategy for developers to communicate intent more so than it is a technical restriction.
 
 ### Strings
 

docs/contributors/design.md

@@ -46,7 +46,7 @@ Gutenberg wants to make it easier to author rich content. This means ensuring go
 
 The initial phase of Gutenberg as described in the kickoff goal is primarily limited to the content area (specifically `post_content`) of posts and pages. Within those confines, we are embracing the web as a vertical river of content by appending blocks sequentially, then adding layout options to each block.
 
-That said, there isn’t any fixed limit to the kind of layouts Gutenberg will be able to create. It’s very possible for Gutenberg to grow beyond the confines of post and page content, to include the whole page — one could think of a theme template as a comma separated list of blocks, like this:
+That said, there isn’t any fixed limit to the kind of layouts Gutenberg will be able to create. It’s very possible for Gutenberg to grow beyond the confines of post and page content, to include the whole page — one could think of a theme template as a comma-separated list of blocks, like this:
 
 ```js
 {

docs/contributors/readme.md

@@ -0,0 +1,11 @@
+# Contributors Guide
+
+Welcome to the Gutenberg Project Contributors Guide.
+
+The following guidelines are in place to create consistency across the project and the numerous contributors. See also the [Contributing Documentation](https://github.com/WordPress/gutenberg/blob/master/CONTRIBUTING.md) for technical details around setup, and submitting your contributions.
+
+* [Coding Guidelines](../../docs/contributors/coding-guidelines.md) outline additional patterns and conventions used in the Gutenberg project.
+* [Copy Guidelines](../../docs/contributors/copy-guide.md)
+* [Design Principles & Vision](../../docs/contributors/design.md)
+
+Please see the table of contents on the left side of the Gutenberg Handbook for the full list of contributor resources.

docs/designers-developers/developers/backward-compatibility/meta-box.md

@@ -27,7 +27,7 @@ After a meta box is converted to a block, it can be declared as existing for bac
 add_meta_box( 'my-meta-box', 'My Meta Box', 'my_meta_box_callback',
 	null, 'normal', 'high',
 	array(
-		'__back_compat_meta_box' => false,
+		'__back_compat_meta_box' => true,
 	)
 );
 ```

docs/designers-developers/developers/block-api/block-edit-save.md

@@ -80,6 +80,24 @@ edit( { attributes, setAttributes, className, isSelected } ) {
 }
 ```
 
+When using attributes that are objects or arrays it's a good idea to copy or clone the attribute prior to updating it:
+
+```js
+// Good - here a new array is created from the old list attribute and a new list item:
+const { list } = attributes;
+const addListItem = ( newListItem ) => setAttributes( { list: [ ...list, newListItem ] } );
+
+// Bad - here the list from the existing attribute is modified directly to add the new list item:
+const { list } = attributes;
+const addListItem = ( newListItem ) => {
+	list.push( newListItem );
+	setAttributes( { list } );
+};
+
+```
+
+Why do this? In JavaScript, arrays and objects are passed by reference, so this practice ensures changes won't affect other code that might hold references to the same data. Furthermore, Gutenberg follows the philosophy of the Redux library that [state should be immutable](https://redux.js.org/faq/immutable-data#what-are-the-benefits-of-immutability)—data should not be changed directly, but instead a new version of the data created containing the changes.
+
 ## Save
 
 The `save` function defines the way in which the different attributes should be combined into the final markup, which is then serialized by Gutenberg into `post_content`.

docs/designers-developers/developers/filters/block-filters.md

@@ -115,7 +115,7 @@ wp.hooks.addFilter(
 
 #### `blocks.switchToBlockType.transformedBlock`
 
-Used to filters an individual transform result from block transformation. All of the original blocks are passed, since transformations are many-to-many, not one-to-one.
+Used to filter an individual transform result from block transformation. All of the original blocks are passed since transformations are many-to-many, not one-to-one.
 
 #### `blocks.getBlockAttributes`
 
@@ -200,7 +200,7 @@ var withClientIdClassName = wp.compose.createHigherOrderComponent( function( Blo
 			{},
 			props,
 			{
-				classsName: "block-" + props.clientId,
+				className: "block-" + props.clientId,
 			}
 		);
 
@@ -322,9 +322,9 @@ function my_plugin_block_categories( $categories, $post ) {
 add_filter( 'block_categories', 'my_plugin_block_categories', 10, 2 );
 ```
 
-You can also display an icon with your block category by setting an `icon` attribute.The value can be the slug of a [WordPress Dashicon](https://developer.wordpress.org/resource/dashicons/).
+You can also display an icon with your block category by setting an `icon` attribute. The value can be the slug of a [WordPress Dashicon](https://developer.wordpress.org/resource/dashicons/).
 
-It is possible to set an SVG as the icon of the category if a custom icon is needed.To do so, the icon should be rendered and set on the frontend, so it can make use of WordPress SVG, allowing mobile compatibility and making the icon more accessible.
+It is possible to set an SVG as the icon of the category if a custom icon is needed. To do so, the icon should be rendered and set on the frontend, so it can make use of WordPress SVG, allowing mobile compatibility and making the icon more accessible.
 
 To set an SVG icon for the category shown in the previous example, add the following example JavaScript code to the editor calling `wp.blocks.updateCategory` e.g:
 ```js
@@ -335,5 +335,5 @@ To set an SVG icon for the category shown in the previous example, add the follo
 	var svgIcon = el( SVG, { width: 20, height: 20, viewBox: '0 0 20 20'}, circle);
 	wp.blocks.updateCategory( 'my-category', { icon: svgIcon } );
 } )();
-``` 
+```
 

docs/designers-developers/developers/tutorials/javascript/extending-the-block-editor.md

@@ -0,0 +1,66 @@
+# Extending the Block Editor
+
+Let's look at using the [Block Style Variation example](../../../../../docs/designers-developers/developers/filters/block-filters.md#block-style-variations) to extend the editor. This example allows you to add your own custom CSS class name to any core block type.
+
+Replace the existing `console.log()` code in your `myguten.js` file with:
+
+```js
+wp.blocks.registerBlockStyle( 'core/quote', {
+    name: 'fancy-quote',
+    label: 'Fancy Quote'
+} );
+```
+
+**Important:** Notice that you are using a function from `wp.blocks` package. This means you must specify it as a dependency when you enqueue the script. Update the `myguten-plugin.php` file to:
+
+```php
+<?php
+/*
+Plugin Name: Fancy Quote
+*/
+
+function myguten_enqueue() {
+	wp_enqueue_script( 'myguten-script',
+		plugins_url( 'myguten.js', __FILE__ ),
+		array( 'wp-blocks')
+	);
+}
+add_action( 'enqueue_block_editor_assets', 'myguten_enqueue' );
+```
+
+The last argument in the `wp_enqueue_script()` function is an array of dependencies. WordPress makes packages available under the `wp` namespace. In the example, you use `wp.blocks` to access the items that the blocks package exports (in this case the `registerBlockStyle()` function).
+
+See [Packages](../../../../../docs/designers-developers/developers/packages.md) for list of available packages and what objects they export.
+
+After you have updated both JavaScript and PHP files, go to the Block Editor and create a new post.
+
+Add a quote block, and in the right sidebar under Styles, you will see your new Fancy Quote style listed.  Click the Fancy Quote to select and apply that style to your quote block.
+
+
+![Fancy Quote Style in Inspector](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/assets/fancy-quote-in-inspector.png)
+
+
+You will not see a visible change, even if you Preview or Publish the post. However, if you look at the source, you will see the `is-style-fancy-quote` class name is now attached to your quote block.
+
+Let's add some style. Go ahead and create a `style.css` file with:
+
+```css
+.is-style-fancy-quote {
+	color: tomato;
+}
+
+```
+
+You enqueue the CSS file by adding the following to your `myguten-plugin.php`:
+
+```php
+function myguten_stylesheet() {
+	wp_enqueue_style( 'myguten-style', plugins_url( 'style.css', __FILE__ ) );
+}
+add_action( 'enqueue_block_assets', 'myguten_stylesheet' );
+```
+
+Now when you view in the editor and published, you will see your Fancy Quote style, a delicious tomato color text.
+
+![Fancy Quote with Style](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/assets/fancy-quote-with-style.png)
+

docs/designers-developers/developers/tutorials/javascript/loading-javascript.md

@@ -0,0 +1,49 @@
+# Loading JavaScript
+
+With the plugin in place, you can add the code that loads the JavaScript. This methodology follows the standard WordPress procedure of enqueuing scripts, see [enqueuing section of the Plugin Handbook](https://developer.wordpress.org/plugins/javascript/enqueuing/).
+
+Add the following code to your `myguten-plugin.php` file:
+
+```php
+function myguten_enqueue() {
+	wp_enqueue_script(
+		'myguten-script',
+		plugins_url( 'myguten.js', __FILE__ )
+	);
+}
+add_action( 'enqueue_block_editor_assets', 'myguten_enqueue' );
+```
+
+The `enqueue_block_editor_assets` hook is used, which is called when the block editor loads, and will enqueue the JavaScript file `myguten.js`.
+
+Create a file called `myguten.js` and add:
+
+```js
+console.log( "I'm loaded!" );
+```
+
+Next, create a new post in the block editor.
+
+We'll check the JavaScript console in your browser's Developer Tools, to see if the message is displayed. If you're not sure what developer tools are, Mozilla's ["What are browser developer tools?"](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/What_are_browser_developer_tools) documentation provides more information, including more background on the [JavaScript console](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/What_are_browser_developer_tools#The_JavaScript_console).
+
+If your code is registered and enqueued correctly, you should see a message in your console:
+
+![Console Log Message Success](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/assets/js-tutorial-console-log-success.png)
+
+**Note for Theme Developers:**  The above method of enqueing is used for plugins. If you are extending the Block Editor for your theme there is a minor difference, you will use the `get_template_directory_uri()` function instead of `plugins_url()`. So for a theme, the enqueue example is:
+
+```php
+function myguten_enqueue() {
+	wp_enqueue_script(
+		'myguten-script',
+		get_template_directory_uri() . '/myguten.js'
+	);
+}
+add_action( 'enqueue_block_editor_assets', 'myguten_enqueue' );
+```
+
+### Recap
+
+At this point, you have a plugin in the directory `wp-content/plugins/myguten-plugin` with two files: the PHP server-side code in `myguten-plugin.php`, and the JavaScript which runs in the browser in `myguten.js`.
+
+This puts all the initial pieces in place for you to start extending the Block Editor.

docs/designers-developers/developers/tutorials/javascript/plugins-background.md

@@ -0,0 +1,16 @@
+# Plugins Background
+
+The primary means of extending WordPress is the plugin. WordPress' [Plugin Basics](https://developer.wordpress.org/plugins/the-basics/) documentation provides for more details on building a plugin. The quickest way to start is to create a new directory in `wp-content/plugins/` to hold your plugin code, for this example you can call it `myguten-plugin`.
+
+Inside of this new directory, create a file called `myguten-plugin.php` which is the server-side code that runs when your plugin is active. For now place the following in that file:
+
+```php
+<?php
+/*
+Plugin Name: Fancy Quote
+*/
+```
+
+To summarize, you should have a directory `wp-content/plugins/myguten-plugin/` which has the single file `myguten-plugin.php`. Once that is in place, go to your plugins list in `wp-admin` and you should see your plugin listed.
+
+Click **Activate** and your plugin will load with WordPress.