Add natural language linting (#335)

* Align with Adobe Glossary terms with exclusion of individual preferences of a project owner Ignore backend and frontend terms * Add symlink for use with VSC * Update PR testing workflow * Fix the textlint violations * Apply suggestions from code review Co-authored-by: Jared Hoover <[email protected]> Co-authored-by: Kevin Harper <[email protected]> * Apply suggestions from code review --------- Co-authored-by: Jared Hoover <[email protected]> Co-authored-by: Kevin Harper <[email protected]>
AdobeDocs · Jul 24, 2024 · e9fc035 · e9fc035
1 parent c414e70
commit e9fc035
Show file tree

Hide file tree

Showing 44 changed files with 185 additions and 138 deletions.
diff --git a/.github/linters/.textlintrc b/.github/linters/.textlintrc
@@ -0,0 +1,39 @@
+{ 
+  "rules": {
+    "terminology": {
+      "severity" : "warning",
+      "exclude": [
+        "back[- ]end(\\w*)",
+        "bug[- ]fix(es)?",
+        "client ?side",
+        "end-?user(s)?",
+        "indexes\\b",
+        "front[- ]end(\\w*)",
+        "Mac ?OS",
+        "OS X",
+        "readme(s)?",
+        "server ?side",
+        "smartphone(s)?",
+        "spell-?check(er|ing)?",
+        "style-?sheet(s)?",
+        "web-?page(s)?",
+        "web[- ]?site(s)?",
+        "white[- ]space",
+        "ZIP"
+      ],
+      "terms": [
+        ["bug[- ]fix", "bugfix"],
+        ["bug-?fixes", "bug fixes"],
+        ["indices\\b", "indexes"],
+        "macOS",
+        "ReadMe",
+        ["smart[- ]phone(s)?", "smartphone$1"],
+        ["spell[- ]?check(er|ing)", "spelling checker$1"],
+        "UNIX",
+        ["web[- ]page(s)?", "webpage$1"],
+        ["web[- ]site(s)?", "website$1"],
+        ["white-?space", "white space"]
+      ]
+   }
+  }
+}
diff --git a/.github/super-linter.env b/.github/super-linter.env
@@ -1,5 +1,8 @@
 IGNORE_GITIGNORED_FILES=true
-VALIDATE_MARKDOWN=true
 MARKDOWN_CONFIG_FILE=.markdownlint.yml
-VALIDATE_YAML=true
+VALIDATE_ALL_CODEBASE=true
+VALIDATE_GITHUB_ACTIONS=true
 VALIDATE_JSON=true
+VALIDATE_MARKDOWN=true
+VALIDATE_NATURAL_LANGUAGE=true
+VALIDATE_YAML=true
diff --git a/.github/workflows/test-pull-request.yml b/.github/workflows/test-pull-request.yml
@@ -1,85 +1,89 @@
 ---
-###########################
-###########################
-## Pull request testing ##
-###########################
-###########################
-name: Latest Pull Request
-
-# Documentation:
-# - Workflow: https://help.github.com/en/articles/workflow-syntax-for-github-actions
-# - SuperLinter: https://github.com/github/super-linter
-# - Link validation: https://github.com/remarkjs/remark-validate-links
-
-######################################################
-# Start the job on a pull request to the main branch #
-######################################################
-on: pull_request
-
-###############
-# Set the Job #
-###############
-jobs:
-  validate:
-    # Set the agent to run on
-    runs-on: ubuntu-latest
-
-    ############################################
-    # Grant status permission for MULTI_STATUS #
-    ############################################
-    permissions:
-      contents: read
-      packages: read
-      statuses: write
-
-    ##################
-    # Load all steps #
-    ##################
-    steps:
-      ##########################
-      # Checkout the code base #
-      ##########################
-      - name: Checkout Code
-        uses: actions/checkout@v4
-        with:
-          # Full git history is needed to get a proper list of changed files
-          # within `super-linter`
-          fetch-depth: 0
-      - run: cat ".github/super-linter.env" >> "$GITHUB_ENV"
-
-      ################################
-      # Run Linters against code base #
-      ################################
-      - name: Lint Code Base
-        #
-        # Use full version number to avoid cases when a next
-        # released version is buggy
-        # About slim image: https://github.com/github/super-linter#slim-image
-        uses: super-linter/super-linter/[email protected]
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          DEFAULT_BRANCH: main
-          VALIDATE_ALL_CODEBASE: false
-          VALIDATE_GITHUB_ACTIONS: true
-
-      - name: Setup Node
-        uses: actions/setup-node@v3
-        with:
-          node-version-file: '.nvmrc'
-          cache: 'yarn'
-          cache-dependency-path: 'yarn.lock'
-
-      - name: Enable Corepack for Yarn
-        run: corepack enable
-
-      - name: Install Dependencies
-        run: yarn install
-        env:
-          YARN_ENABLE_IMMUTABLE_INSTALLS: false
-
-      - name: Check links
-        run: yarn test
-
-      - name: Build site
-        if: ${{ success() }}
-        run: yarn build
+  ###########################
+  ###########################
+  ## Pull request testing ##
+  ###########################
+  ###########################
+  name: Validate pull request
+
+  # Documentation:
+  # - Workflow: https://help.github.com/en/articles/workflow-syntax-for-github-actions
+  # - SuperLinter: https://github.com/github/super-linter
+  # - Link validation: https://github.com/remarkjs/remark-validate-links
+
+  ######################################################
+  # Start the job on a pull request to the main branch #
+  ######################################################
+  on: pull_request
+
+  ###############
+  # Set the Job #
+  ###############
+  jobs:
+    lint:
+      # Set the agent to run on
+      runs-on: ubuntu-latest
+
+      ############################################
+      # Grant status permission for MULTI_STATUS #
+      ############################################
+      permissions:
+        contents: read
+        packages: read
+        statuses: write
+
+      ##################
+      # Load all steps #
+      ##################
+      steps:
+        ##########################
+        # Checkout the code base #
+        ##########################
+        - name: Checkout Code
+          uses: actions/checkout@v4
+          with:
+            # Full git history is needed to get a proper list of changed files
+            # within `super-linter`
+            fetch-depth: 0
+        - name: Load super-linter configuration
+          run: cat .github/super-linter.env >> "$GITHUB_ENV"
+
+        ################################
+        # Run Linters against code base #
+        ################################
+        - name: Lint Code Base
+          #
+          # Use full version number to avoid cases when a next
+          # released version is buggy
+          # About slim image: https://github.com/github/super-linter#slim-image
+          uses: super-linter/super-linter/[email protected]
+          env:
+            GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+            DEFAULT_BRANCH: main
+    test_and_build:
+      runs-on: ubuntu-latest
+      needs: lint
+      steps:
+        - name: Checkout Code
+          uses: actions/checkout@v4
+
+        - name: Setup Node
+          uses: actions/setup-node@v3
+          with:
+            node-version-file: '.nvmrc'
+            cache: 'yarn'
+            cache-dependency-path: 'yarn.lock'
+
+        - name: Enable Corepack for Yarn
+          run: corepack enable
+
+        - name: Install Dependencies
+          run: yarn install
+          env:
+            YARN_ENABLE_IMMUTABLE_INSTALLS: false
+
+        - name: Check links
+          run: yarn test
+
+        - name: Build site
+          run: yarn build
diff --git a/.textlintrc b/.textlintrc
@@ -0,0 +1 @@
+.github/linters/.textlintrc
diff --git a/README.md b/README.md
@@ -15,7 +15,7 @@ Ensure that your local environment matches the prerequisites described in the Ad
 
 To build the site locally:
 
-1. Clone this repo.
+1. Clone this repository.
 1. Install project dependencies.
 
    ```bash

diff --git a/src/_includes/graphql/payment-methods/payflow-link-workflow.md b/src/_includes/graphql/payment-methods/payflow-link-workflow.md
@@ -4,7 +4,7 @@
 
 1. The client runs the [`placeOrder`](/src/pages/graphql/schema/cart/mutations/place-order.md) mutation, which creates an order and begins the authorization process.
 
-1. The application requests a secure token from the Paypal gateway.
+1. The application requests a secure token from the PayPal gateway.
 
 1. The gateway response includes a secure token, a secure token ID, and the URL to use for requesting the form in step 9. This token secures the data for a one-time transaction and is valid for 30 minutes.
 

diff --git a/src/pages/get-started/api-security.md b/src/pages/get-started/api-security.md
@@ -159,7 +159,7 @@ If you need to change the default limits for REST endpoints, then edit the `weba
 
 The maximum page size setting controls the pagination of various web API responses. By default, the maximum value is `300`. You can change the default in the Admin by selecting **Stores** > Settings > **Configuration** > **Services** > **Web API Input Limits** or **GraphQl Input Limits** >  **Maximum Page Size** field.
 
-[GraphQL security configuration](../graphql/usage/security-configuration.md describes how to set the maximum page size in GraphQL.
+[GraphQL security configuration](../graphql/usage/security-configuration.md) describes how to set the maximum page size in GraphQL.
 
 ## Default page size
 

diff --git a/src/pages/get-started/authentication/gs-authentication-oauth.md b/src/pages/get-started/authentication/gs-authentication-oauth.md
@@ -101,7 +101,7 @@ You must include these request parameters in the `Authorization`  header in the
 
 Parameter | Description
 --- | ---
-`oauth_consumer_key` | The consumer key value that you retrieve after you register the integration.
+`oauth_consumer_key` | The consumer key-value that you retrieve after you register the integration.
 `oauth_nonce` | A random value that is uniquely generated by the application.
 `oauth_signature` | A generated value (signature)
 `oauth_signature_method` | The name of the signature method used to sign the request. Must be the value `HMAC-SHA256`.
@@ -128,7 +128,7 @@ To use the access token to make web API calls:
 
 You must include these request parameters in the `Authorization` request header in the call:
 
-*  `oauth_consumer_key`. The customer key value provided after the registration of the application.
+*  `oauth_consumer_key`. The customer key-value provided after the registration of the application.
 *  `oauth_nonce`. A random value, uniquely generated by the application.
 *  `oauth_signature_method`. The name of the signature method used to sign the request. Valid values are: `HMAC-SHA256`.
 *  `oauth_signature`. A generated value (signature).
@@ -137,7 +137,7 @@ You must include these request parameters in the `Authorization` request header
 
 ## The OAuth signature
 
-All OAuth handshake requests and Web Api requests include the signature as part of Authorization header. Its generated as follows:
+All OAuth handshake requests and Web API requests include the signature as part of Authorization header. Its generated as follows:
 
 You concatenate a set of URL-encoded attributes and parameters to construct the signature base string.
 

diff --git a/src/pages/get-started/authentication/gs-authentication-session.md b/src/pages/get-started/authentication/gs-authentication-session.md
@@ -30,7 +30,7 @@ Similarly, if an admin is logged in to the Admin and the JavaScript widget invok
 
 Admin session-based authentication is not currently possible for API endpoints.
 
-The session based authentication functionality is restricted to AJAX calls. Direct browser requests cannot be made due to security vulnerabilities. A developer can create a custom storefront widget that can issue requests without additional authentication steps.
+The session based authentication functionality is restricted to Ajax calls. Direct browser requests cannot be made due to security vulnerabilities. A developer can create a custom storefront widget that can issue requests without additional authentication steps.
 
 ## Related topic
 

diff --git a/src/pages/get-started/gs-curl.md b/src/pages/get-started/gs-curl.md
@@ -156,7 +156,7 @@ $this->curl->setCookies($cookies);
 
 ### Example usage
 
-For example, the `Magento\Marketplace\Model\Partners` class gets partners info using cURL from the api of Magento connect.
+For example, the `Magento\Marketplace\Model\Partners` class gets partners info using cURL from the API of Magento connect.
 
 ```php
 namespace Magento\Marketplace\Model;
@@ -271,7 +271,7 @@ class Partners
 ```
 
 First off all the cURL client instance is created in `__construct`.
-Method `getPartners` uses the cURL client makes POST request using cURL, the `post` method takes the first parameter the URL to the api of `magento-connect`, second parameter is empty array, then the option `CURLOPT_REFERER` added by `setOptions` method of the cURL client.
+Method `getPartners` uses the cURL client makes POST request using cURL, the `post` method takes the first parameter the URL to the API of `magento-connect`, second parameter is empty array, then the option `CURLOPT_REFERER` added by `setOptions` method of the cURL client.
 As result the script call `getBody` method of the cURL client.
 
 #### Related topics

diff --git a/src/pages/get-started/index.md b/src/pages/get-started/index.md
@@ -19,7 +19,7 @@ The Adobe Commerce and Magento Open Source web API framework provides integrator
 
 *  All accounts and integrations are assigned resources that they have access to. The API framework checks that any call has the authorization to perform the request.
 
-*  Any native or third-party service can be [configured as a web API](https://developer.adobe.com/commerce/php/development/components/web-api/services/) with a few lines of xml. To configure a web API, you define XML elements and attributes in a `webapi.xml` configuration file. If a service is not defined in a configuration file, it will not be exposed at all.
+*  Any native or third-party service can be [configured as a web API](https://developer.adobe.com/commerce/php/development/components/web-api/services/) with a few lines of XML. To configure a web API, you define XML elements and attributes in a `webapi.xml` configuration file. If a service is not defined in a configuration file, it will not be exposed at all.
 
 *  The framework is based on the CRUD (create, read, update, delete) & search model. The system does not currently support webhooks.
 
@@ -37,7 +37,7 @@ The APIs can be used to perform a wide array of tasks. For example:
 
 *  Integrate with a CMS (Content Management System). Currently, content tagging is not supported.
 
-*  Create JavaScript widgets in the storefront or on the Admin panel. The widget makes AJAX calls to access services.
+*  Create JavaScript widgets in the storefront or on the Admin panel. The widget makes Ajax calls to access services.
 
 ## How do I get started?
 

diff --git a/src/pages/get-started/rate-limiting.md b/src/pages/get-started/rate-limiting.md
@@ -8,7 +8,7 @@ keywords:
 
 # Rate limiting
 
-In a carding attack, an attacker tries to determine which credit card numbers are valid, usually in batches of thousands. Attackers can use similar techniques to brute force missing details, such as the expiration date. Adobe Commerce merchants can be targeted by this attack type through their shops and integrations with 3rd-party payment gateways.
+In a carding attack, an attacker tries to determine which credit card numbers are valid, usually in batches of thousands. Attackers can use similar techniques to brute force missing details, such as the expiration date. Adobe Commerce merchants can be targeted by this attack type through their shops and integrations with third-party payment gateways.
 
 As of Adobe Commerce 2.4.7, you can configure rate limiting for the payment information transmitted using REST and GraphQL. This added layer of protection allows merchants to prevent and decrease the volume of carding attacks that test many credit card numbers at once.
 
@@ -212,7 +212,7 @@ sales/backpressure/enabled - 1
 
 ## Log contents
 
-If rate limiting has been enabled for the payment information endpoint and the GraphQl mutation via the UI/CLI, but the Redis service connection for store log requests has not been configured in the `app/etc/env.php` file, then the rate-limiting will not apply. The behavior will be the same if this option is disabled, but the application logs (`<magento-root>/var/log/system.log`) will contain the following message:
+If rate limiting has been enabled for the payment information endpoint and the GraphQL mutation via the UI/CLI, but the Redis service connection for store log requests has not been configured in the `app/etc/env.php` file, then the rate-limiting will not apply. The behavior will be the same if this option is disabled, but the application logs (`<magento-root>/var/log/system.log`) will contain the following message:
 
 ```text
 ...
@@ -237,7 +237,7 @@ Cache-Control: no-store
 {"message":"Too Many Requests","trace":null}
 ```
 
-If rate limiting is applied to a GraphQl request, then a response with HTTP status code `200 - Ok` will be generated and all relevant information will be present in the response body.
+If rate limiting is applied to a GraphQL request, then a response with HTTP status code `200 - Ok` will be generated and all relevant information will be present in the response body.
 
 Example:
 

diff --git a/src/pages/get-started/web-api-functional-testing.md b/src/pages/get-started/web-api-functional-testing.md
@@ -10,7 +10,7 @@ keywords:
 
 The Web API testing framework allows you to test Web APIs from the client application point of view. The tests can be used with either REST or SOAP. The REST or SOAP adapter that runs the tests is specified in PHPUnit configuration. See [How to Run the Tests](#how-to-run-the-tests) for more information.
 
-To run Web API tests for GraphQl, see [GraphQL functional testing](../graphql/develop/functional-testing.md).
+To run Web API tests for GraphQL, see [GraphQL functional testing](../graphql/develop/functional-testing.md).
 
 ## Implementation Details
 

diff --git a/src/pages/graphql/develop/debugging.md b/src/pages/graphql/develop/debugging.md
@@ -11,12 +11,12 @@ keywords:
 
 This topic provides recommendations on how to debug GraphQL requests.
 
-## Debugging with PHPStorm and Xdebug
+## Debugging with PhpStorm and Xdebug
 
 When [using GraphiQL](../index.md#how-to-access-graphql) or any other client for testing GraphQL queries, you might need to debug the request processing.
 You can use Xdebug for debugging the PHP execution of a GraphQL query just as you would for other HTTP requests.
 To start debugging, add the `?XDEBUG_SESSION_START=PHPSTORM` parameter to the endpoint URL.
-The following example shows how to establish a connection between Xdebug and PHPStorm IDE.
+The following example shows how to establish a connection between Xdebug and PhpStorm IDE.
 
 ```http
 http://<magento2-3-server>/graphql?XDEBUG_SESSION_START=PHPSTORM

diff --git a/src/pages/graphql/develop/functional-testing.md b/src/pages/graphql/develop/functional-testing.md
@@ -172,7 +172,7 @@ The specified fixtures will now execute on every test run.
 
 Every fixture should have a rollback file. A rollback is a set of operations that remove changes introduced by the fixture from the system once the test is completed.
 
-The rollback filename should correspond to the original fixture filename postfixed by `_rollback` keyword. For example, if the fixture file name is `virtual_product.php`, name the rollback file `virtual_product_rollback.php`.
+The rollback filename should correspond to the original fixture filename postfixed by `_rollback` keyword. For example, if the fixture filename is `virtual_product.php`, name the rollback file `virtual_product_rollback.php`.
 
 The following fixture rollback removes the newly-created product from the database.
 

diff --git a/src/pages/graphql/release-notes.md b/src/pages/graphql/release-notes.md
@@ -38,7 +38,7 @@ The [Magento Open Source 2.4.0 Release Notes](https://experienceleague.adobe.com
 
 -  **Guest carts can now be merged with customer carts.** The [`mergeCarts`](schema/cart/mutations/merge.md) mutation transfers the contents of a guest cart into the cart of a logged-in customer.
 -  **A customer can start an order on one device and complete it on another.** Use the [`customerCart`](schema/customer/queries/cart.md) query to obtain the cart ID for a logged-in customer.
--  **Layered navigation can use custom filters.** The `filter` attribute of the [`products`](schema/products/queries/products.md) query now requires the `ProductAttributeFilterInput` object. You can specify a pre-defined filter in this object, or [define a custom filter](usage/custom-filters.md). As a result, layered navigation on your website filters on the attributes you need.
+-  **Layered navigation can use custom filters.** The `filter` attribute of the [`products`](schema/products/queries/products.md) query now requires the `ProductAttributeFilterInput` object. You can specify a predefined filter in this object, or [define a custom filter](usage/custom-filters.md). As a result, layered navigation on your website filters on the attributes you need.
 -  **You can search categories by ID, name, and/or URL key.** The [`categoryList`](schema/products/queries/category-list.md) query replaces the deprecated `category` query.
 -  **A customer can add bundle and downloadable products to the cart with the [`addBundleProductsToCart`](schema/cart/mutations/add-bundle-products.md) and [`addDownloadableProductsToCart`](schema/cart/mutations/add-downloadable-products.md) mutations.**
 -  **The [`ProductInterface`](schema/products/interfaces/index.md) supports fixed product taxes (such as WEEE).** Use the [`storeConfig`](schema/store/queries/store-config.md) query to determine whether the store supports these taxes.