Merge branch 'master' into update-multiselect-widget-documentation

Author: dobooth

.github/CONTRIBUTING.md

@@ -66,19 +66,8 @@ The following guidelines may answer most of your questions and help you get star
 - Familiarize yourself with the organization and conventions of our existing documentation before creating a pull request. Changes that are consistent with our style and conventions have a higher acceptance rate.
 
     - If you need to update the site navigation, ask for help in Slack ([#devdocs](https://magentocommeng.slack.com/messages/CAN932A3H)).
-    - We use symbolic links for topics that are the same across versions of Magento. Remove the symbolic link and add a new file if your changes are unique to a specific version. Copy and paste a previous version of the topic to get started.
 
-        For example:
-
-        ```bash
-        git rm guides/v2.3/install-gde/composer.md
-        ```
-
-        ```bash
-        cp guides/v2.2/install-gde/composer.md guides/v2.3/install-gde/composer.md
-        ```
-
-- Make sure that you update the correct version(s) of documentation (v2.2, v2.3). If you are not sure what directory to put your content in, just do your best. We can help re-locate it (if necessary) during the review process.
+- Ensure that you update the correct version(s) of documentation (v2.2, v2.3). If you are not sure what directory to put your content in, just do your best. We can help re-locate it (if necessary) during the review process.
 - Review your work for basic typos, formatting errors, or ambiguous sentences before opening a pull request.
 - Revise pull requests according to review feedback. We will close pull requests that require an inordinate amount of time to review and process (especially for minor changes) if you fail to make revisions according to review feedback.
 - Do not directly contact DevDocs team members or maintainers on Slack to review your pull request unless it has been open for more than five days. We have a process and queue for pull requests that everyone must follow.
@@ -116,6 +105,7 @@ We provide templates to help you get started writing new content and understandi
 The Markdown (.md) file's metadata is a set of YAML key-value pairs. The metadata section is located at the top of each file. For more info, see the [Basic Template](https://devdocs.magento.com/guides/v2.3/contributor-guide/templates/basic_template.html).
 
 ```yaml
+
 ---
 group: install2
 title: Continue with your installation
@@ -129,6 +119,45 @@ title: Continue with your installation
 | `group`       | Defines the topic's guide or section. Use the table of contents `.yml` file name. This loads your left-side navigation. We will help during the PR process to add new files to the `.yml` file. |
 | `title`       | Sets the title of the page in the HTML metadata and the main title on the page.  |
 
+## Symbolic links
+
+We use symbolic links for topics that are the same across versions of Magento. A file is symlinked if the entire content of the file is a path to the original version, such as [ext-best-practices/tutorials/serialized-to-json-data-upgrade.md](https://github.com/magento/devdocs/blob/master/guides/v2.3/ext-best-practices/tutorials/serialized-to-json-data-upgrade.md). Note that some editors will automatically follow symlinks so it might not be clear if a file is symlinked or not. Check the file on Github directly to be sure.
+
+### Create a symbolic link
+
+When you create a new topic (create a new `.md` file) and its content is the same for 2.2 and 2.3 versions, create a symbolic link.
+
+For example, if you created a new file for v.2.2---`guides/v2.2/install-gde/new-doc-topic.md`---and its content is the same for v.2.3, use the command below to create the symbolic link.
+
+```bash
+cd <DEVDOCS_REPOSITORY_ROOT_DIR>
+```
+
+```bash
+ln -s guides/v2.2/install-gde/new-doc-topic.md guides/v2.3/install-gde/new-doc-topic.md
+```
+
+If you have an image that is identical between versions, it is should placed in `/common/images`. Please optimize images before committing them to the repository.
+If done correctly, the symbolic link path will start with 3 or 4 instances of `../`, as the above example shows.
+
+### Remove a symbolic link
+
+If your changes are unique to a specific version, remove the symbolic link and add a new file. Copy and paste a previous version of the topic to get started.
+
+The removal should use the `git rm` command specifically. Deleting the file through the regular file system might cause issues with the repository.
+
+For example:
+
+```bash
+git rm guides/v2.3/install-gde/composer.md
+```
+
+```bash
+cp guides/v2.2/install-gde/composer.md guides/v2.3/install-gde/composer.md
+```
+
+Once you have the copy in place, you can edit it with the version-specific information.
+
 ## Report an issue
 
 If you find a typo or errors in Magento DevDocs, you can either fix it with a pull request (as described above) or you can report it by creating an issue in the DevDocs GitHub repository.

.github/ISSUE_TEMPLATE/COMMUNITY_ISSUE_TEMPLATE.md

@@ -8,6 +8,7 @@ about: Create an issue related to a community engineering effort
 <!-- (REQUIRED) Provide information for the doc request including any Community code issues or PRs, Magento versions, or devdoc pages. -->
 
 Type of Doc:
+
 - [ ] New topic
 - [ ] Topic Update, Devdoc link:
 - [ ] Other
@@ -17,13 +18,15 @@ Magento 2 GitHub Issue: https://github.com/magento/devdocs/issues/link
 Magento 2 GitHub PR: https://github.com/magento/devdocs/pull/link
 
 Magento 2 version:
+
 - [ ] 2.1.X
 - [ ] 2.2.X
 - [ ] 2.3.X
 - [ ] back port
 - [ ] forward port
 
 Notifications of Changes:
+
 - [ ] Changes to Admin interface?
 - [ ] New software requirements?
 - [ ] New REST endpoints or updated GraphQL query syntax?

README.md

@@ -111,7 +111,8 @@ If rake fails on your environment, generate the preview [using jekyll](#using-je
 ### To minimize build time locally:
 
 1. Create a `_config.local.yml` file at the root of the project directory and exclude all versions except the one that you want to preview.
-The following example will generate Magento 2.2 documentation only.
+
+   The following example will generate Magento 2.2 documentation only.
 
    ```yaml
     exclude:
@@ -138,7 +139,9 @@ The following example will generate Magento 2.2 documentation only.
    ```
    $ rake preview
    ```
+
    This command:
+
    * Checks your environment according to the dependencies in `Gemfile.lock`.
    * Removes the `_site/` directory, which contains previously generated preview files.
    * Generates a new preview and opens the landing page in a web browser.

_data/toc/javascript-developer-guide.yml

@@ -109,6 +109,9 @@ pages:
         - label: RowBuilder widget
           url: /javascript-dev-guide/widgets/widget-row-builder.html
 
+        - label: Sortable widget
+          url: /javascript-dev-guide/widgets/widget-sortable.html
+
         - label: Sticky widget
           url: /javascript-dev-guide/widgets/widget_sticky.html
 

_includes/cache/page-cache-overview.md

@@ -35,4 +35,3 @@ Reverse proxies serve "public" or shared content to more than one user. However,
 -   **[Public]({{ page.baseurl }}/extension-dev-guide/cache/page-caching/public-content.html)** - Public content is stored server side in your reverse proxy cache storage (e.g., file system, database, Redis, or Varnish) and is available to multiple customers. Examples of public content include header, footer, and category listing.
 
 -   **[Private]({{ page.baseurl }}/extension-dev-guide/cache/page-caching/private-content.html)** - Private content is stored client side (e.g., browser) and is specific to an individual customer. Examples of private content include wishlist, shopping cart, customer name, and address. You should limit stored private content to a small portion of the page's total content.
-</div>

_includes/cloud/enable-ssh.md

@@ -28,6 +28,7 @@ If you have SSH keys, a directory listing is displayed similar to the following:
 If you do not have SSH keys, you need to generate the keys for adding to your Magento ECE account and GitHub account. See [Create a new SSH key pair](#ssh-create-new-key-pair).
 
 If you already have SSH keys, continue to:
+
 * [Add a public SSH key to your Magento account](#ssh-add-to-account) section
 * [Add your SSH key to your GitHub account](https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/)
 

_includes/cloud/note-route-all-placeholder.md

@@ -1,2 +1,2 @@
-{: .bs-callout-info}
-The following route configuration examples use route templates with placeholders. The `{default}` placeholder represents the default domain configured for your site. If your project has multiple domains, use the `{all}` placeholder instead to configure routing for the default domain and all aliases. See [Configure routes]({{ page.baseurl }}/cloud/project/project-conf-files_routes.html).
+{:.bs-callout-info}
+The following route configuration examples use route templates with placeholders. The `{default}` placeholder represents the default domain configured for your site. If your project has multiple domains, use the `{all}` placeholder to configure routing for the default domain and all aliases. See [Configure routes]({{ page.baseurl }}/cloud/project/project-conf-files_routes.html).

_includes/config/es-elasticsearch-magento.md

@@ -30,6 +30,7 @@ Unless you changed Elasticsearch server settings, the defaults should work. Skip
 |**Enable Elasticsearch HTTP Auth**|Click **Yes** only if you enabled authentication for your Elasticsearch server. If so, provide a username and password in the provided fields.|
 
 {:start="4"}
+
 1. Click **Test Connection**.
 
 You will see either:
@@ -49,11 +50,11 @@ If so, try the following:
 
 * Make sure the Elasticsearch server is running.
 * If the Elasticsearch server is on a different host from Magento, log in to the Magento server and ping the Elasticsearch host. Resolve network connectivity issues and test the connection again.
-* Examine the command window in which you started Elasticsearch for stack traces and exceptions. You must resolve those before you continue.
-In particular, make sure you started Elasticsearch as a user with `root` privileges.
+* Examine the command window in which you started Elasticsearch for stack traces and exceptions. You must resolve those before you continue. In particular, make sure you started Elasticsearch as a user with `root` privileges.
 * Make sure that [UNIX firewall and SELinux]({{ page.baseurl }}/config-guide/elasticsearch/es-overview.html#firewall-selinux) are both disabled, or set up rules to enable Elasticsearch and Magento to communicate with each other.
 * Verify the value of the **Elasticsearch Server Hostname** field. Make sure the server is available. You can try the server's IP address instead.
 * Use the command `netstat -an | grep **listen-port**` command to verify that the port specified in the **Elasticsearch Server Port** field is not being used by another process.
+
   For example, to see if Elasticsearch is running on its default port, use the following command:
 
   ```bash

_includes/config/multi-site_verify.md

@@ -14,6 +14,7 @@ Unless you have DNS set up for your stores' URLs, you must add a static route to
 You're done!
 
 {:.bs-callout .bs-callout-info}
+
 * Additional tasks might be required to deploy multiple websites in a hosted environment; check with your hosting provider for more information.
 * Additional tasks are required to set up {{site.data.var.ece}}; for more information, see [Set up multiple Cloud websites or stores]({{ page.baseurl }}/cloud/project/project-multi-sites.html)
 

_includes/config/setup-cron.md

@@ -5,11 +5,13 @@ Magento uses cron for two sets of tasks, and for each, cron can run with a diffe
 *	PHP command-line configuration: The general cron job that reindexes indexers, generates e-mails, generates the sitemap, and so on.
 
 	You can find the command-line configuration using the command `php --ini`.
+
 *	Web server PHP plug-in configuration: Two other cron jobs are used by the [Component Manager and System Upgrade utilities]({{ page.baseurl }}/comp-mgr/bk-compman-upgrade-guide.html).
 
 	You can find the web server plug-in configuration using [`phpinfo.php`]({{ page.baseurl }}/install-gde/prereq/optional.html#install-optional-phpinfo).
 
 {:.bs-callout .bs-callout-warning}
+
 *	To avoid issues during installation and upgrade, we strongly recommend you apply the same PHP settings to both the PHP command-line configuration and to the PHP web server plug-in's configuration. For more information, see [Required PHP settings]({{ page.baseurl }}/install-gde/prereq/php-settings.html).
 *	In a multi-node system, crontab can run on only one node. This applies to you only if you set up more than one webnode for reasons related to performance or scalability.