Merge pull request #5676 from magento/sync-develop

Sync develop with master

Author: jeff-matthews

.github/CONTRIBUTING.md

@@ -58,33 +58,33 @@ The following diagram shows the contribution workflow:
 
 The following guidelines may answer most of your questions and help you get started:
 
-- Write content using Markdown. See the [Templates](#templates) section for examples.
-- Review existing [pull requests](https://github.com/magento/devdocs/pulls) and [issues](https://github.com/magento/devdocs/issues) to avoid duplicating work.
-- For large contributions, or changes that include multiple files, [open an issue](#report-an-issue) and discuss it with us first. This helps prevent duplicate or unnecessary work.
-- Do not make global find-and-replace changes without first creating an issue and discussing it with us. Global changes can have unintended consequences.
-- Combine multiple small changes (such as minor editorial and technical changes) into a single pull request. This helps us efficiently and effectively facilitate your contribution.
-- 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.
+-  Write content using Markdown. See the [Templates](#templates) section for examples.
+-  Review existing [pull requests](https://github.com/magento/devdocs/pulls) and [issues](https://github.com/magento/devdocs/issues) to avoid duplicating work.
+-  For large contributions, or changes that include multiple files, [open an issue](#report-an-issue) and discuss it with us first. This helps prevent duplicate or unnecessary work.
+-  Do not make global find-and-replace changes without first creating an issue and discussing it with us. Global changes can have unintended consequences.
+-  Combine multiple small changes (such as minor editorial and technical changes) into a single pull request. This helps us efficiently and effectively facilitate your contribution.
+-  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)).
+   -  If you need to update the site navigation, ask for help in Slack ([#devdocs](https://magentocommeng.slack.com/messages/CAN932A3H)).
 
-- 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.
+-  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.
 
 ## Tips for writing content
 
 Use the following guidelines to help you with the writing process:
 
-- Focus your efforts on providing useful information for your fellow Magento developers and community members. For example, consider providing or revising code samples, important notes, and clarifying vague or ambiguous content.
-- Define the goal of your topic. What exactly do you want to teach the reader?
-- Make the title of your topic reflect the content.
-- Keep your sentences concise. Separate conceptual information from procedural steps.
-- Batch several small changes into a single pull request (instead of separate ones) to ensure your contributions are approved and merged quickly. Have several typo fixes across several areas of documentation? Combine them into a single PR.
-- Remember to write in present tense, use the second person, and use active voice (not passive). For example, _"The log captures commands, output..."_.
-- Use notes to alert readers about important details.
-- Use cross-references to other topics sparingly. We can help you with the syntax if it is not clear. The template provides an example you can use.
-- Need help with markdown? See our [templates](#templates).
+-  Focus your efforts on providing useful information for your fellow Magento developers and community members. For example, consider providing or revising code samples, important notes, and clarifying vague or ambiguous content.
+-  Define the goal of your topic. What exactly do you want to teach the reader?
+-  Make the title of your topic reflect the content.
+-  Keep your sentences concise. Separate conceptual information from procedural steps.
+-  Batch several small changes into a single pull request (instead of separate ones) to ensure your contributions are approved and merged quickly. Have several typo fixes across several areas of documentation? Combine them into a single PR.
+-  Remember to write in present tense, use the second person, and use active voice (not passive). For example, _"The log captures commands, output..."_.
+-  Use notes to alert readers about important details.
+-  Use cross-references to other topics sparingly. We can help you with the syntax if it is not clear. The template provides an example you can use.
+-  Need help with markdown? See our [templates](#templates).
 
 ### Review changes locally
 
@@ -94,11 +94,11 @@ _(Optional)_ To review your changes in HTML output, follow the instructions in t
 
 We provide templates to help you get started writing new content and understanding Markdown formatting:
 
-- **General topic template** - [Markdown](https://github.com/magento/devdocs/blob/master/guides/v2.3/contributor-guide/templates/basic_template.md) | [HTML](https://devdocs.magento.com/guides/v2.3/contributor-guide/templates/basic_template.html): This is a template for writing any topic with example formats and styles.
-- **Tutorial templates**: These templates provide example formats and styles for step-by-step instructions (like how-tos). Each file adds navigation buttons when content is generated. Templates include:
-  - First introduction topic - [Markdown](https://github.com/magento/devdocs/blob/master/guides/v2.3/contributor-guide/templates/tutorial-template-first.md) | [HTML](https://devdocs.magento.com/guides/v2.3/contributor-guide/templates/tutorial-template-first.html): Introduction to a tutorial for prerequisites and listing steps
-  - Middle topic - [Markdown](https://github.com/magento/devdocs/blob/master/guides/v2.3/contributor-guide/templates/tutorial-template-middle.md) |  [HTML](https://devdocs.magento.com/guides/v2.3/contributor-guide/templates/tutorial-template-middle.html): Use for each step in a tutorial.
-  - Final step topic - [Markdown](https://github.com/magento/devdocs/blob/master/guides/v2.3/contributor-guide/templates/tutorial-template-last.md) | [HTML](https://devdocs.magento.com/guides/v2.3/contributor-guide/templates/tutorial-template-last.html): Use for the last step of the tutorial.
+-  **General topic template** - [Markdown](https://github.com/magento/devdocs/blob/master/guides/v2.3/contributor-guide/templates/basic_template.md) | [HTML](https://devdocs.magento.com/guides/v2.3/contributor-guide/templates/basic_template.html): This is a template for writing any topic with example formats and styles.
+-  **Tutorial templates**: These templates provide example formats and styles for step-by-step instructions (like how-tos). Each file adds navigation buttons when content is generated. Templates include:
+   -  First introduction topic - [Markdown](https://github.com/magento/devdocs/blob/master/guides/v2.3/contributor-guide/templates/tutorial-template-first.md) | [HTML](https://devdocs.magento.com/guides/v2.3/contributor-guide/templates/tutorial-template-first.html): Introduction to a tutorial for prerequisites and listing steps
+   -  Middle topic - [Markdown](https://github.com/magento/devdocs/blob/master/guides/v2.3/contributor-guide/templates/tutorial-template-middle.md) |  [HTML](https://devdocs.magento.com/guides/v2.3/contributor-guide/templates/tutorial-template-middle.html): Use for each step in a tutorial.
+   -  Final step topic - [Markdown](https://github.com/magento/devdocs/blob/master/guides/v2.3/contributor-guide/templates/tutorial-template-last.md) | [HTML](https://devdocs.magento.com/guides/v2.3/contributor-guide/templates/tutorial-template-last.html): Use for the last step of the tutorial.
 
 ### Edit metadata
 
@@ -137,7 +137,7 @@ cd <DEVDOCS_REPOSITORY_ROOT_DIR>
 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 you have an image that is identical between versions, it 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
@@ -168,19 +168,19 @@ You must complete the issue template. We will close your issue if you fail to co
 
 You can provide feedback using the following options:
 
-- Have general feedback? Create an issue on [GitHub DevDocs](https://github.com/magento/devdocs/issues/new/choose).
-- Have feedback on a specific DevDocs page? Click the **Give us feedback** link at the top right of the page to report on the currently open topic.
+-  Have general feedback? Create an issue on [GitHub DevDocs](https://github.com/magento/devdocs/issues/new/choose).
+-  Have feedback on a specific DevDocs page? Click the **Give us feedback** link at the top right of the page to report on the currently open topic.
 
-     ![Report an issue](https://devdocs.magento.com/common/images/contribute-feedback-link.png)
+   ![Report an issue](https://devdocs.magento.com/common/images/contribute-feedback-link.png)
 
-- Have a Community code contribution that needs documentation? Create an issue to [request DevDocs content](https://github.com/magento/devdocs/issues/new?template=COMMUNITY_ISSUE_TEMPLATE.md).
+-  Have a Community code contribution that needs documentation? Create an issue to [request DevDocs content](https://github.com/magento/devdocs/issues/new?template=COMMUNITY_ISSUE_TEMPLATE.md).
 
 ## Contact DevDocs
 
 Have a question? Need help? Magento DevDocs, Maintainers, and other Contributors are available through:
 
-- [Slack](https://magentocommeng.slack.com/messages/CAN932A3H) ([Join us](http://tinyurl.com/engcom-slack))
-- [Twitter @MagentoDevDocs](https://twitter.com/MagentoDevDocs)
-- [E-mail](mailto:[email protected])
+-  [Slack](https://magentocommeng.slack.com/messages/CAN932A3H) ([Join us](http://tinyurl.com/engcom-slack))
+-  [Twitter @MagentoDevDocs](https://twitter.com/MagentoDevDocs)
+-  [E-mail](mailto:[email protected])
 
 Thank you for contributing your brilliance to Magento DevDocs!!

.github/MAINTAINER_GUIDELINES.md

@@ -4,12 +4,12 @@ In general, the same [guidelines](https://devdocs.magento.com/guides/v2.3/contri
 
 ## General expectations
 
-- Self assign issues/pull requests (mostly pull requests)
-  - Review and approve or request changes
-  - Enforce the use of the issue/pull requests template
-  - Ask contributors to link to the code base to validate documentation updates when applicable
-  - Ask contributors not to contribute to v2.0 docs
-- If a maintainer creates a pull request, it should be reviewed by another maintainer or DevDocs staff member
+-  Self assign issues/pull requests (mostly pull requests)
+   -  Review and approve or request changes
+   -  Enforce the use of the issue/pull requests template
+   -  Ask contributors to link to the code base to validate documentation updates when applicable
+   -  Ask contributors not to contribute to v2.0 docs
+-  If a maintainer creates a pull request, it should be reviewed by another maintainer or DevDocs staff member
 
 ## Labels
 
@@ -51,8 +51,8 @@ We prefer Markdown over HTML (in most cases). You can use [kramdown](https://kra
 
 Before merging a pull request to the `master` branch, it must pass automated testing. Testing takes about 30 minutes to complete for each pull request, so we created a workflow to save time for small changes.
 
-- **Individual pull requests to `master`**—15 individual pull requests to `master` x 30 minutes per pull request = 7.5 hrs of testing time
-- **Multiple pull requests using `small_changes`**—1 `small_changes` pull request (containing 15 individual pull requests) to `master` x 30 minutes = 30 minutes of testing time
+-  **Individual pull requests to `master`**—15 individual pull requests to `master` x 30 minutes per pull request = 7.5 hrs of testing time
+-  **Multiple pull requests using `small_changes`**—1 `small_changes` pull request (containing 15 individual pull requests) to `master` x 30 minutes = 30 minutes of testing time
 
 This workflow is for typos, formatting issues, and minor text additions or deletions. It is not for substantial new content, changes to tables, new files, or files that have been moved.
 
@@ -63,7 +63,7 @@ Periodically, we will create a pull request from `small_changes` to `master` and
 1. Review the pull request and either approve it or request changes.
 1. Apply the `Small changes` label if one of the following labels should also be applied:
 
-   - `Editorial`
-   - `Technical`
+   -  `Editorial`
+   -  `Technical`
 
-1. That's it! A devdocs-admin will run tests and merge.
+1. That's it! A devdocs-admin will run tests and merge.

.github/workflows/main.yml

@@ -0,0 +1,24 @@
+name: Markdown linting test
+
+on:
+  pull_request:
+    branches:
+      - master
+      - develop
+    paths:
+      - '*.md'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    
+    steps:
+    - uses: actions/checkout@v1
+    - name: Set up Ruby
+      uses: actions/setup-ruby@v1
+      with:
+        ruby-version: 2.6
+    - name: Install gems
+      run: bundle install
+    - name: Run mdl
+      run: rake test:md