MC-35509: Updated the software update guide module with the safe upgrade tool documentation

src/_data/toc/software-update-guide.yml

@@ -21,6 +21,28 @@ pages:
         - label: Update and upgrade checklist
           url: /comp-mgr/prereq/prereq_compman-checklist.html
 
+    - label: Safe Upgrade Tool
+      url: /safe-upgrade-tool/introduction.html
+      versionless: true
+      edition: ee-only
+      children:
+
+        - label: Prerequisites
+          url: /safe-upgrade-tool/prerequisites.html
+          versionless: true
+
+        - label: Install
+          url: /safe-upgrade-tool/install.html
+          versionless: true
+
+        - label: Run the tool
+          url: /safe-upgrade-tool/run.html
+          versionless: true
+
+        - label: Developer information
+          url: /safe-upgrade-tool/developer.html
+          versionless: true
+
     - label: Magento Marketplace example
       url: /comp-mgr/marketplace/marketplace.html
       include_versions: ["2.3"]

src/_includes/layout/page-header.html

@@ -42,4 +42,10 @@ <h2 class="page-subtitle no_toc">{{ page.subtitle }}</h2>
   </div>
   {% endif %}
 
+  {% if page.url contains "safe-upgrade-tool/" %}
+  <div class="message-banner">
+    This tool is still in ALPHA with limited scope. If you are a Magento Commerce user you can download it at <a href="https://repo.magento.com/">Magento repo</a>.
+  </div>
+  {% endif %}
+
 </section>

src/guides/v2.3/comp-mgr/bk-compman-upgrade-guide.md

@@ -53,6 +53,9 @@ Related topics
 
 Complete the tasks discussed in [Prerequisites].
 
+ {:.bs-callout-info}
+See the [Safe Upgrade Tool ALPHA]({{site.baseurl}}/safe-upgrade-tool/introduction.html) for more information about the new Magento CLI tool that helps you update your Magento software.
+
 <!-- ABBREVIATIONS -->
 
 *[contributing developer]: A developer who contributes code to the Magento 2 CE codebase

src/guides/v2.4/comp-mgr/bk-compman-upgrade-guide.md

@@ -48,6 +48,9 @@ Related topics
 
 Complete the tasks discussed in [Prerequisites].
 
+ {:.bs-callout-info}
+See the [Safe Upgrade Tool ALPHA]({{site.baseurl}}/safe-upgrade-tool/introduction.html) for more information about the new Magento CLI tool that helps you update your Magento software.
+
 <!-- ABBREVIATIONS -->
 
 *[contributing developer]: A developer who contributes code to the Magento 2 CE codebase

src/safe-upgrade-tool/developer.md

@@ -0,0 +1,109 @@
+---
+group: software-update-guide
+title: Developer information
+ee_only: True
+functional_areas:
+  - Upgrade
+---
+
+This topic contains information for developers who want to know more technical information about the Magento Safe Upgrade Tool ALPHA (SUT). It is focused on developers who work closely with the Magento source code. You can use this knowledge to customize the SUT's components.
+
+## Magento API index integration
+
+Magento API index integration is an internal integration solution that comprehends a set of tools to explore Magento Extensions developed by Magento, an Adobe Company, Magento Partners and 3rd party vendors based on static code analysis.
+
+The integration with Magento API index is done through:
+
+`Sut\Domain\MRay\MRayInterface`
+
+It is implemented through the `config/services.yaml` file. Its value decides where the response of methods `api()` and `modules()` comes from.
+
+Edit this file to customize the response according to your installation. Just replace the value assigned to `Sut\Domain\MRay\MRayInterface`:
+
+### Example of a custom value
+
+`Sut\Domain\MRay\MRayInterface : "@sut_mray_mock"`
+
+In the previous example, the SUT uses `@sut_mray_mock` as the `MRayInterface` implementation. The responses from the `api()` and `modules()` methods come from the following files:
+
+*  `dev/mray_mock_files/api.json`
+*  `dev/mray_mock_files/modules.json`
+
+{:.bs-callout-info}
+When you make changes to the `services.yaml` file, delete the `var/cache/` folder to correctly apply them.
+
+## Unit testing
+
+To run the unit tests, execute one of the following commands:
+
+*  `vendor/bin/phpunit tests/unit`
+*  `vendor/bin/phpunit -c tests/unit/phpunit.xml.dist tests/unit`
+*  `vendor/bin/phpunit -c tests/unit/phpunit.xml.dist --testsuite=unit-tests`
+
+## Integration testing
+
+To run the integration tests, execute one of the following commands:
+
+*  `vendor/bin/phpunit -c tests/integration/phpunit.xml.dist tests/integration`
+*  `vendor/bin/phpunit -c tests/integration/phpunit.xml.dist --testsuite=integration-tests`
+
+## Acceptance testing
+
+1. Before executing acceptance tests, you must set the Magento URL in the `phpunit` configuration file.
+1. Copy the default `tests/acceptance/phpunit.xml` file (without the .dist suffix).
+1. Change the `TESTS_BASE_URL` value to point to the Magento URL that you want to test.
+1. To run the acceptance tests, execute one of the following commands:
+
+   *  `vendor/bin/phpunit -c tests/acceptance/phpunit.xml tests/acceptance`
+   *  `vendor/bin/phpunit -c tests/acceptance/phpunit.xml --testsuite=acceptance-tests`
+
+## JS unit testing for GraphQL
+
+We used the [Jest](https://jestjs.io/docs/en/getting-started.html) framework to create these JS unit tests:
+
+{:.bs-callout-info}
+To run JS unit tests for GraphQL, you must have Node.js installed.
+
+### Node.js
+
+To install Node.js on your system, see the Node.js [documentation](https://nodejs.dev/learn/how-to-install-nodejs).
+
+The following instructions are for MacOS systems:
+
+1. Open a terminal and navigate to the `graphql-schema-compatibility/` directory.
+1. Install project dependencies:
+
+   ```bash
+   npm install
+   ```
+
+1. Run unit tests or `jest`:
+
+   ```bash
+   npm run unit-test
+   ```
+
+The tests are inside `graphql-schema-compatibility/test/js/unit`.
+
+The string schemas for testing are inside `dev/graphql_schemas`.
+
+## Complexity score
+
+The **complexity score** is a figure that indicates how difficult an upgrade from the current version to the new one might be. Lower numbers indicate easier upgrades.
+
+{:.bs-callout-info}
+Complexity scores range between 0 and ∞.
+
+This score is based on the results extracted from the analysis:
+
+*  Number of issues identified
+*  Severity of issues identified
+
+The SUT calculates this score according to the following formula:
+
+### Complexity score formula
+
+`Complexity Score = 2 * (# of errors) + 1 * (# of warnings)`
+
+{:.bs-callout-warning}
+These are absolute values.

src/safe-upgrade-tool/install.md

@@ -0,0 +1,110 @@
+---
+group: software-update-guide
+title: Install
+ee_only: True
+functional_areas:
+  - Upgrade
+---
+
+The Safe Upgrade Tool ALPHA (SUT) is a command line (CLI) tool that checks a Magento instance against a specific version by analyzing all the non-Magento modules installed on it.
+
+{:.bs-callout-warning}
+At the moment this is an ALPHA version with limited scope, available for all Magento Commerce merchants, only validating PHP Magento APIs and GraphQL schema.
+
+## Workflow
+
+The following diagram shows the expected workflow when running the SUT:
+
+![SUT Diagram](img/mvp-diagram-v2.png)
+
+### Who is the SUT for?
+
+The following use case describes the typical process for a Magento partner to upgrade a client's Magento instance:
+
+1. A partner's Software Engineer downloads the SUT package from the [Magento repository](https://repo.magento.com/) and executes it during the beta phase of the newest Magento release.
+1. The Software Engineer sees that there are several customized areas broken in the inventory and catalog modules and they also get a complexity score of X. See the [Developer information guide]({{site.baseurl}}/safe-upgrade-tool/developer.html) for more information on the complexity score.
+1. With this information, the Software Engineer is able to understand the complexity of the upgrade and is able to relay this information back to the partner's Account Manager.
+1. The Account Manager creates a timeline and cost for the Magento upgrade, which allows them to get their manager's approval.
+1. With their manager's approval, the Software Engineer works on the required code modifications to fix the broken modules.
+1. The Software Engineer runs the SUT tool one more time with a Magento pre-release to ensure there are no new issues and that their code changes fixed the problems found during the beta phase.
+1. Everything check’s out and the Software Engineer pushes the code to a staging environment where regression tests confirm all tests are green, which allows them to release the latest Magento version to production the same day that the Magento pre-release is released.
+
+![SUT audience](img/audience-sut.png)
+
+#### Contact SUT
+
+To connect with the SUT team:
+
+1. Contact us on the Engineering Slack channel [Magento Safe Upgrade Tool](https://magentocommeng.slack.com/archives/C019Y143U9F).
+1. Send us an email at [sut@adobe.com](mailto:sut@adobe.com).
+
+See the [Resources]({{site.baseurl}}/community/resources/resources.html) page for more information.
+
+## Prerequisites
+
+See [prerequisites]({{site.baseurl}}/safe-upgrade-tool/prerequisites.html) for more information.
+
+{:.bs-callout-info}
+You can run the SUT in any operating system. There is no requirement to run the SUT where your Magento instance is located. It is necessary for SUT to have access to the source code of the Magento instance. For example, you can install the SUT on one server and point it at your Magento installation on another server.
+
+If you are running SUT against a Magento instance with large modules and files, the tool might require a high amount of RAM, at least 2GB RAM.
+
+### Recommended actions
+
+Magento best practice is not to have 2 modules with the same name, if this happens SUT will show a segmentation fault error in which case you have to analyze each module independently with the option `-m`:
+
+  ```bash
+  bin/sut upgrade:check /(instance_path) --coming-version=2.4.1 -m /(module_path)
+  ```
+
+If you get memory issues while executing SUT it is recommended to use the `-m` command to run the tool against a specific module.
+
+## Install
+
+To install the SUT, you must install the necessary prerequisites:
+
+*  Magento access keys
+*  Composer
+*  Node.js (only required to check GraphQL compatibility)
+
+Refer to the [SUT installation]({{site.baseurl}}/safe-upgrade-tool/install.html#install).
+
+### Magento access keys
+
+You must have [Magento access keys]({{site.baseurl}}/marketplace/sellers/profile-information.html#access-keys) to download and use the SUT. Add your Magento access keys to your `auth.json` file, which is located at `~/.composer` by default.
+
+{:.bs-callout-warning}
+Check your **COMPOSER_HOME** environment variable to see where the `auth.json` file is located.
+
+The **public key** corresponds to the _username_ whereas the **private key** is the _password_:
+
+### Example of Magento access keys
+
+```json
+    "http-basic": {
+        "repo.magento.com": {
+            "username": "YOUR_MAGENTO_PUBLIC_KEY",
+            "password": "YOUR_MAGENTO_PRIVATE_KEY"
+        }
+    },
+```
+
+### Composer
+
+Clone the [safe-upgrade-tool](https://github.com/magento-commerce/safe-upgrade-tool) repository and run `composer install` in your terminal to install dependencies.
+
+{:.bs-callout-warning}
+If the **Magento access keys** are not correctly configured, the SUT will not install and you will get errors when running the `composer install` command.
+
+### Node.js
+
+To install Node.js, see the Node.js [documentation](https://nodejs.dev/learn/how-to-install-nodejs).
+
+{:.bs-callout-info}
+Node.js is only a requirement to check GraphQL compatibility.
+
+## Third-party extensions
+
+Magento recommends that you contact your search engine vendor to determine whether your extension is fully compatible with Magento 2.4.
+
+See [Run the tool]({{site.baseurl}}/safe-upgrade-tool/run.html) for information about executing the SUT tool.

src/safe-upgrade-tool/introduction.md

@@ -0,0 +1,20 @@
+---
+group: software-update-guide
+title: Introduction
+ee_only: True
+functional_areas:
+  - Upgrade
+---
+
+The Safe Upgrade Tool ALPHA (SUT) is a command line (CLI) tool that checks a Magento instance against a specific version by analyzing all the non-Magento modules installed in it.
+
+The SUT identifies potential problems that must be fixed in your custom code before attempting to upgrade to a newer version of Magento.
+
+The SUT returns a list of errors and warnings that you must address before upgrading to a new version of Magento.
+
+It is distributed as a Composer package with every release of a Magento version. See [Developer]({{site.baseurl}}/safe-upgrade-tool/developer.html) topic for more information.
+
+Refer to the [Install]({{site.baseurl}}/safe-upgrade-tool/install.html) for first steps with SUT.
+
+{:.bs-callout-warning}
+At the moment this is an ALPHA version with limited scope, available for all Magento Commerce merchants, only validating PHP Magento APIs and GraphQL schema.

src/safe-upgrade-tool/prerequisites.md

@@ -0,0 +1,25 @@
+---
+group: software-update-guide
+title: Prerequisites
+ee_only: True
+functional_areas:
+  - Upgrade
+---
+
+Running the Safe Upgrade Tool ALPHA (SUT) helps you identify what you must do **before** upgrading Magento.
+
+The minimum requirements to run the SUT are:
+
+| **Requirements** | **Constraints** |
+|----------------|-----------------|
+| PHP version| >= 7.3 |
+| Composer | none |
+| Node.js | An optional requirement. Only required to check GraphQL compatibility. |
+| Memory limitations | At least 2GB RAM |
+| Magento Access keys | none |
+| MC or Magento Open Source | none |
+{:style="table-layout:auto;"}
+
+You can run the SUT in any operating system. There is no requirement to run the SUT where your Magento instance is located.
+
+It is necessary for SUT to have access to the source code of the Magento instance. For example, you can install SUT on one server and point it at your Magento installation on another server. Refer to the [install]({{site.baseurl}}/safe-upgrade-tool/install.html#install) for more information.