MC-35509: Updated the software update guide module with the safe upgrade tool documentation (#8314)

* Added SUT topics

* Added dev topic for sut

* Added diagram workflow SUT

* Fixed issues

* Created use guide and divided install and welcome guide

* Reviewed topic and fixed issues

* Reviewed topic and fixed issues

* Fixed url

* Reviewed dev topic and fixed issues

* fixed in toc url

* Added sut tracking page and reorganized pages

* Reviewed topic sut tracking and added audience in welcome guide

* Reviewed topics

* Reviewed topics and added page for SUT

* Fix linting issues

* Fix linting issues

* Fix linting issues 3

* Fix linting issues 4

* Fix linting issues 5

* Fix linting issues

* Fix linting issues

* Fix linting issues

* Fix linting issues

* Fix linting issues

* Fix linting issues rule md30

* Fix linting issues rule md30

* Fix linting issues rule md06 & md36

* Fix linting issues rule md36

* Added link to the sut section in the main software update guide topic

* moved SUT section under guides to keep it versionless

* Added link to the sut section in the main 2.3 software update guide topic

* moved sut folder and modified urls as per peer review

* Added versionless:true to TOC as per peer review

* Modified files for sut after peer review

* Fixed linting issue MD029

* continue modifying files after peer review

* continue modifying files after peer review - include H3 or H4 for examples

* added links to composer and new relic

* added links to composer and new relic

* fixed linting rule issues md009

* fixed topics after peer review

* fixed linting rule issues md029

* Removed acronym from directory path

* Applied suggestions from initiall peer review

* Copy edited files that were not part of innitial peer review

* reviewed topics and pages after discussion with ENG about SUT public docs. Removed tracking topic

* Fixed linting issue MD029

* Added a banner in page-header.html

* Added a banner in page-header.html

* Modified banner as ALPHA

* Updated topic after peer review

* Updated topic after peer review - continue

* Removed entry in TOC about tracking

* Reviewed comments in PR

* Added memory limits as per technical review

* Updated introduction with correct tool name from Ampersand

* Updated information for memory limitations and complexity formula

* Fixed url in page-header html

* Fixed pages and toc with commerce-only banner

* Fixed toc with commerce-only banner

* Added changes as per MC-40435

* Updated PR after product review

* Updated PR after linting review

* Updated PR after product review

* Updated PR after product review - 2

* Updated PR after slack/email information requested by product

* Updated PR after slack/email information requested by product

* Updated PR after slack/email information requested by product

* Modified contact section

Co-authored-by: Jeff Matthews <[email protected]>

Author: danidelcar

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/img/audience-sut.png

@@ -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 [[email protected]](mailto:[email protected]).
+
+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/img/mvp-diagram-v2.png

@@ -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.