WordPress · pinarol · Dec 11, 2018 · Dec 6, 2018 · Dec 7, 2018 · Dec 7, 2018
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -166,9 +166,9 @@ Maintaining dozens of npm packages is difficult—it can be tough to keep track
 
 The developer who proposes a change (pull request) is responsible to choose the correct version increment (`major`, `minor`, or `patch`) according to the following guidelines:
 
-- Major version X (X.y.z | X > 0) should be changed with any backwards-incompatible/"breaking" change. This will usually occur at the final stage of deprecating and removing of a feature.
-- Minor version Y (x.Y.z | x > 0) should be changed when you add functionality or change functionality in a backwards-compatible manner. It must be incremented if any public API functionality is marked as deprecated.
-- Patch version Z (x.y.Z | x > 0) should be incremented when you make backwards-compatible bug fixes.
+- Major version X (X.y.z | X > 0) should be changed with any backward incompatible/"breaking" change. This will usually occur at the final stage of deprecating and removing of a feature.
+- Minor version Y (x.Y.z | x > 0) should be changed when you add functionality or change functionality in a backward compatible manner. It must be incremented if any public API functionality is marked as deprecated.
+- Patch version Z (x.y.Z | x > 0) should be incremented when you make backward compatible bug fixes.
 
 When in doubt, refer to [Semantic Versioning specification](https://semver.org/).
 

diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md
@@ -122,3 +122,5 @@ This list is manually curated to include valuable contributions by volunteers th
 | @sharazghouri | @sharaz |
 | @jakeparis | @jakeparis |
 | @designsimply | @designsimply |
+| @aldavigdis | @aldavigdis |
+| @miya0001 | @miyauchi |
diff --git a/README.md b/README.md
@@ -7,7 +7,7 @@
 This repo is the development hub for the <a href="https://make.wordpress.org/core/2017/01/04/focus-tech-and-design-leads/">editor focus in WordPress Core</a>. `Gutenberg` is the project name.
 
 ## Getting started
-- **Download:** If you want to use the latest release with your WordPress site, <a href="https://wordpress.org/plugins/gutenberg/">download the latest release from the WordPress.org plugins repository</a>. 
+- **Download:** If you want to use the latest release with your WordPress site, <a href="https://wordpress.org/plugins/gutenberg/">download the latest release from the WordPress.org plugins repository</a>.
 - **Discuss:** Conversations and discussions take place in <a href="https://wordpress.slack.com/messages/C02QB2JS7">`#core-editor` channel on the Making WordPress Slack</a>.
 - **Contribute:** Development of Gutenberg happens in this GitHub repo. Get started by <a href="https://github.com/WordPress/gutenberg/blob/master/CONTRIBUTING.md">reading the contributing guidelines</a>.
 - **Learn:** <a href="https://wordpress.org/gutenberg/">Discover more about the project on WordPress.org</a>.
@@ -44,7 +44,7 @@ Check out the <a href="https://github.com/WordPress/gutenberg/blob/master/docs/r
 
 ## Compatibility
 
-Posts are backwards compatible, and shortcodes will still work. We are continuously exploring how highly-tailored meta boxes can be accommodated, and are looking at solutions ranging from a plugin to disable Gutenberg to automatically detecting whether to load Gutenberg or not. While we want to make sure the new editing experience from writing to publishing is user-friendly, we’re committed to finding a good solution for highly-tailored existing sites.
+Posts are backward compatible, and shortcodes will still work. We are continuously exploring how highly-tailored meta boxes can be accommodated, and are looking at solutions ranging from a plugin to disable Gutenberg to automatically detecting whether to load Gutenberg or not. While we want to make sure the new editing experience from writing to publishing is user-friendly, we’re committed to finding a good solution for highly-tailored existing sites.
 
 ## The stages of Gutenberg
 

diff --git a/...rs/tutorials/block-tutorial/inspector.png → ...designers-developers/assets/inspector.png b/...rs/tutorials/block-tutorial/inspector.png → ...designers-developers/assets/inspector.png
diff --git a/docs/designers-developers/assets/toolbar-text.png b/docs/designers-developers/assets/toolbar-text.png
diff --git a/docs/designers-developers/developers/README.md b/docs/designers-developers/developers/README.md
@@ -26,7 +26,7 @@ You can also filter certain aspects of the editor; this is documented on the [Ed
 
 **Porting PHP meta boxes to blocks and Gutenberg plugins is highly encouraged!**
 
-Discover how [Meta Box](../../../docs/designers-developers/developers/backwards-compatibility/meta-box.md) support works in Gutenberg.
+Discover how [Meta Box](../../../docs/designers-developers/developers/backward-compatibility/meta-box.md) support works in Gutenberg.
 
 ## Theme Support
 

diff --git a/docs/designers-developers/developers/backward-compatibility/README.md b/docs/designers-developers/developers/backward-compatibility/README.md
@@ -0,0 +1 @@
+# Backward Compatibility
diff --git a/...s/backwards-compatibility/deprecations.md → ...rs/backward-compatibility/deprecations.md b/...s/backwards-compatibility/deprecations.md → ...rs/backward-compatibility/deprecations.md
@@ -1,6 +1,6 @@
 # Deprecations
 
-Gutenberg's deprecation policy is intended to support backwards-compatibility for releases, when possible. The current deprecations are listed below and are grouped by _the version at which they will be removed completely_. If your plugin depends on these behaviors, you must update to the recommended alternative before the noted version.
+Gutenberg's deprecation policy is intended to support backward compatibility for releases, when possible. The current deprecations are listed below and are grouped by _the version at which they will be removed completely_. If your plugin depends on these behaviors, you must update to the recommended alternative before the noted version.
 
 ## 4.5.0
 - `Dropdown.refresh()` has been deprecated as the contained `Popover` is now automatically refreshed.

diff --git a/...opers/backwards-compatibility/meta-box.md → ...lopers/backward-compatibility/meta-box.md b/...opers/backwards-compatibility/meta-box.md → ...lopers/backward-compatibility/meta-box.md
@@ -21,7 +21,7 @@ WordPress will fall back to the Classic editor, where the meta box will continue
 
 Explicitly setting `__block_editor_compatible_meta_box` to `true` will cause WordPress to stay in Gutenberg (assuming another meta box doesn't cause a fallback).
 
-After a meta box is converted to a block, it can be declared as existing for backwards compatibility:
+After a meta box is converted to a block, it can be declared as existing for backward compatibility:
 
 ```php
 add_meta_box( 'my-meta-box', 'My Meta Box', 'my_meta_box_callback',
@@ -32,7 +32,7 @@ add_meta_box( 'my-meta-box', 'My Meta Box', 'my_meta_box_callback',
 );
 ```
 
-When Gutenberg is used, this meta box will no longer be displayed in the meta box area, as it now only exists for backwards compatibility purposes. It will continue to display correctly in the Classic editor, should some other meta box cause a fallback.
+When Gutenberg is used, this meta box will no longer be displayed in the meta box area, as it now only exists for backward compatibility purposes. It will continue to display correctly in the Classic editor, should some other meta box cause a fallback.
 
 ### Meta Box Data Collection
 
@@ -42,7 +42,7 @@ See `lib/register.php gutenberg_trick_plugins_into_registering_meta_boxes()`
 
 `gutenberg_collect_meta_box_data()` is hooked in later on `admin_head`. It will run through the functions and hooks that `post.php` runs to register meta boxes; namely `add_meta_boxes`, `add_meta_boxes_{$post->post_type}`, and `do_meta_boxes`.
 
-A copy of the global `$wp_meta_boxes` is made then filtered through `apply_filters( 'filter_gutenberg_meta_boxes', $_meta_boxes_copy );`, which will strip out any core meta boxes, standard custom taxonomy meta boxes, and any meta boxes that have declared themselves as only existing for backwards compatibility purposes.
+A copy of the global `$wp_meta_boxes` is made then filtered through `apply_filters( 'filter_gutenberg_meta_boxes', $_meta_boxes_copy );`, which will strip out any core meta boxes, standard custom taxonomy meta boxes, and any meta boxes that have declared themselves as only existing for backward compatibility purposes.
 
 Then each location for this particular type of meta box is checked for whether it is active. If it is not empty a value of true is stored, if it is empty a value of false is stored. This meta box location data is then dispatched by the editor Redux store in `INITIALIZE_META_BOX_STATE`.
 
@@ -82,3 +82,5 @@ Most PHP meta boxes should continue to work in Gutenberg, but some meta boxes th
 - Plugins relying on selectors that target the post title, post content fields, and other metaboxes (of the old editor).
 - Plugins relying on TinyMCE's API because there's no longer a single TinyMCE instance to talk to in Gutenberg.
 - Plugins making updates to their DOM on "submit" or on "save".
+
+Please also note that if your plugin triggers a PHP warning or notice to be output on the page, this will cause the HTML document type (`<!DOCTYPE html>`) to be output incorrectly. This will cause the browser to render using "Quirks Mode", which is a compatibility layer that gets enabled when the browser doesn't know what type of document it is parsing. The block editor is not meant to work in this mode, but it can _appear_ to be working just fine. If you encounter issues such as *meta boxes overlaying the editor* or other layout issues, please check the raw page source of your document to see that the document type definition is the first thing output on the page. There will also be a warning in the JavaScript console, noting the issue.
diff --git a/docs/designers-developers/developers/backwards-compatibility/README.md b/docs/designers-developers/developers/backwards-compatibility/README.md
diff --git a/docs/designers-developers/developers/block-api/README.md b/docs/designers-developers/developers/block-api/README.md
@@ -4,8 +4,8 @@ Blocks are the fundamental element of the Gutenberg editor. They are the primary
 
 ## Registering a block
 
-All blocks must be registered before they can be used in the editor. You can learn about block registration, and the available options, in the [block registration](block-api/block-registration.md) documentation.
+All blocks must be registered before they can be used in the editor. You can learn about block registration, and the available options, in the [block registration](../../../../docs/designers-developers/developers/block-api/block-registration.md) documentation.
 
 ## Block `edit` and `save`
 
-The `edit` and `save` functions define the editor interface with which a user would interact, and the markup to be serialized back when a post is saved. They are the heart of how a block operates, so they are [covered separately](block-api/block-edit-save.md).
+The `edit` and `save` functions define the editor interface with which a user would interact, and the markup to be serialized back when a post is saved. They are the heart of how a block operates, so they are [covered separately](../../../../docs/designers-developers/developers/block-api/block-edit-save.md).
diff --git a/docs/designers-developers/developers/themes/theme-support.md b/docs/designers-developers/developers/themes/theme-support.md
@@ -4,7 +4,7 @@ The new Blocks include baseline support in all themes, enhancements to opt-in to
 
 There are a few new concepts to consider when building themes:
 
-- **Editor Color Palette** - A default set of colors is provided, but themes and register their own and optionally lock users into picking from the defined palette.
+- **Editor Color Palette** - A default set of colors is provided, but themes can register their own and optionally lock users into picking from the defined palette.
 - **Editor Text Size Palette** - A default set of sizes is provided, but themes and register their own and optionally lock users into picking from preselected sizes.
 - **Responsive Embeds** - Themes must opt-in to responsive embeds.
 - **Frontend & Editor Styles** - To get the most out of blocks, theme authors will want to make sure Core styles look good and opt-in, or write their own styles to best fit their theme.

diff --git a/...rs/developers/tutorials/block-tutorial/block-controls-toolbars-and-inspector.md b/...rs/developers/tutorials/block-tutorial/block-controls-toolbars-and-inspector.md
@@ -4,7 +4,7 @@ To simplify block customization and ensure a consistent experience for users, th
 
 ## Toolbar
 
-<img src="https://cldup.com/jUslj672CK.png" width="391" height="79" alt="toolbar">
+![Screenshot of the rich text toolbar applied to a paragraph block inside the block editor](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/assets/toolbar-text.png)
 
 When the user selects a block, a number of control buttons may be shown in a toolbar above the selected block. Some of these block-level controls are included automatically if the editor is able to transform the block to another type, or if the focused element is an RichText component.
 
@@ -171,7 +171,7 @@ Note that `BlockControls` is only visible when the block is currently selected a
 
 ## Inspector
 
-<img src="https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/developers/tutorials/block-tutorial/inspector.png" with="281" height="527" alt="inspector">
+![Screenshot of the inspector panel focused on the settings for a paragraph block](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/assets/inspector.png)
 
 The inspector is used to display less-often-used settings or settings that require more screen space. The inspector should be used for **block-level settings only**.
 

diff --git a/docs/designers-developers/glossary.md b/docs/designers-developers/glossary.md
@@ -1,21 +1,61 @@
 # Glossary
 
-- **Attribute sources**: An object describing the attributes shape of a block. The keys can be named as most appropriate to describe the state of a block type. The value for each key is a function which describes the strategy by which the attribute value should be extracted from the content of a saved post's content. When processed, a new object is created, taking the form of the keys defined in the attribute sources, where each value is the result of the attribute source function.
-- **Attributes**: The object representation of the current state of a block in post content. When loading a saved post, this is determined by the attribute sources for the block type. These values can change over time during an editing session when the user modifies a block, and are used when determining how to serialize the block.
-- **Block**: The abstract term used to describe units of markup that, composed together, form the content or layout of a webpage. The idea combines concepts of what in WordPress today we achieve with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience.
-- **Block Categories**: These are not a WordPress taxonomy, but instead used internally to sort blocks in the Block Inserter.
-- **Block Inserter**: Primary interface for selecting from the available blocks, triggered by plus icon buttons on Blocks or in the top-left of the editor interface.
-- **Block name**: A unique identifier for a block type, consisting of a plugin-specific namespace and a short label describing the block's intent. e.g. `core/image`
-- **Block type**: In contrast with the blocks composing a particular post, a block type describes the blueprint by which any block of that type should behave. So while there may be many images within a post, each behaves consistent with a unified image block type definition.
-- **Classic block**:
-- **Dynamic block**: A type of block where the content of which may change and cannot be determined at the time of saving a post, instead calculated any time the post is shown on the front of a site. These blocks may save fallback content or no content at all in their JavaScript implementation, instead deferring to a PHP block implementation for runtime rendering.
-- **RichText**: A common component enabling rich content editing including bold, italics, hyperlinks, etc. It is not too much unlike the single editor region of the legacy post editor, and is in fact powered by the same TinyMCE library.
-- **Inspector**: A block settings region shown in place of the post settings when a block is selected. Fields may be shown here to allow the user to customize the selected block.
-- **Post settings**: A sidebar region containing metadata fields for the post, including scheduling, visibility, terms, and featured image.
-- **Reusable block**:
-- **Sidebar**:
-- **Serialization**: The process of converting a block's attributes object into HTML markup, typically occurring when saving the post.
-- **Static block**: A type of block where the content of which is known at the time of saving a post. A static block will be saved with HTML markup directly in post content.
-- **TinyMCE**: [TinyMCE](https://www.tinymce.com/) is a web-based JavaScript WYSIWYG (What You See Is What You Get) editor.
-- **Toolbar**: A set of button controls. In the context of a block, usually referring to the toolbar of block controls shown above the selected block.
-- **Template**:
+<dl>
+<dt>Attribute sources</dt>
+<dd>An object describing the attributes shape of a block. The keys can be named as most appropriate to describe the state of a block type. The value for each key is a function which describes the strategy by which the attribute value should be extracted from the content of a saved post's content. When processed, a new object is created, taking the form of the keys defined in the attribute sources, where each value is the result of the attribute source function.</dd>
+
+<dt>Attributes</dt>
+<dd>The object representation of the current state of a block in post content. When loading a saved post, this is determined by the attribute sources for the block type. These values can change over time during an editing session when the user modifies a block, and are used when determining how to serialize the block.</dd>
+
+<dt>Block</dt>
+<dd>The abstract term used to describe units of markup that, composed together, form the content or layout of a webpage. The idea combines concepts of what in WordPress today we achieve with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience.</dd>
+
+<dt>Block Categories</dt>
+<dd>These are not a WordPress taxonomy, but instead used internally to sort blocks in the Block Inserter.</dd>
+
+<dt>Block Inserter</dt>
+<dd>Primary interface for selecting from the available blocks, triggered by plus icon buttons on Blocks or in the top-left of the editor interface.</dd>
+
+<dt>Block name</dt>
+<dd>A unique identifier for a block type, consisting of a plugin-specific namespace and a short label describing the block's intent. e.g. <code>core/image</code></dd>
+
+<dt>Block type</dt>
+<dd>In contrast with the blocks composing a particular post, a block type describes the blueprint by which any block of that type should behave. So while there may be many images within a post, each behaves consistent with a unified image block type definition.</dd>
+
+<dt>Classic block</dt>
+<dd>A block which embeds the TinyMCE editor as a block, TinyMCE was the base of the previous core editor. Older content created prior to the block editor will be loaded in to a single Classic block.</dd>
+
+<dt>Dynamic block</dt>
+<dd>A type of block where the content of which may change and cannot be determined at the time of saving a post, instead calculated any time the post is shown on the front of a site. These blocks may save fallback content or no content at all in their JavaScript implementation, instead deferring to a PHP block implementation for runtime rendering.</dd>
+
+<dt>Inspector</dt>
+<dd>A block settings region shown in place of the post settings when a block is selected. Fields may be shown here to allow the user to customize the selected block.</dd>
+
+<dt>Post settings</dt>
+<dd>A sidebar region containing metadata fields for the post, including scheduling, visibility, terms, and featured image.</dd>
+
+<dt>RichText</dt>
+<dd>A common component enabling rich content editing including bold, italics, hyperlinks, etc. It is not too much unlike the single editor region of the legacy post editor, and is in fact powered by the same TinyMCE library.</dd>
+
+<dt>Reusable block</dt>
+<dd>A block that is saved and then can be shared as a reusable, repeatable piece of content.</dd>
+
+<dt>Sidebar</dt>
+<dd>The panel on the right which contains the document and block settings. The sidebar is toggled using the Settings gear icon.</dd>
+
+<dt>Serialization</dt>
+<dd>The process of converting a block's attributes object into HTML markup, which occurs each time a block is edited.</dd>
+
+<dt>Static block</dt>
+<dd>A type of block where the content of which is known at the time of saving a post. A static block will be saved with HTML markup directly in post content.</dd>
+
+<dt>TinyMCE</dt>
+<dd><a href="https://www.tinymce.com/">TinyMCE</a> is a web-based JavaScript WYSIWYG (What You See Is What You Get) editor.</dd>
+
+<dt>Toolbar</dt>
+<dd>A set of button controls. In the context of a block, usually referring to the toolbar of block controls shown above the selected block.</dd>
+
+<dt>Template</dt>
+<dd> A template is a pre-defined arrangement of blocks, possibly with predefined attributes or placeholder content. You can provide a template for a post type, to give users a starting point when creating a new piece of content, or inside a custom block with the <code>InnerBlocks</code> component. See the templates documentation for more information. See <a href="../../developers/block-api/block-templates.md">templates documentation</a> for more information.</dd>
+
+</dl>