diff --git a/src/_data/toc/software-update-guide.yml b/src/_data/toc/software-update-guide.yml index e54415c4101..792a1b374e1 100644 --- a/src/_data/toc/software-update-guide.yml +++ b/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"] diff --git a/src/_includes/layout/page-header.html b/src/_includes/layout/page-header.html index 8061b813381..eeb7e409cd3 100644 --- a/src/_includes/layout/page-header.html +++ b/src/_includes/layout/page-header.html @@ -42,4 +42,10 @@

{{ page.subtitle }}

{% endif %} + {% if page.url contains "safe-upgrade-tool/" %} +
+ This tool is still in ALPHA with limited scope. If you are a Magento Commerce user you can download it at Magento repo. +
+ {% endif %} + diff --git a/src/guides/v2.3/comp-mgr/bk-compman-upgrade-guide.md b/src/guides/v2.3/comp-mgr/bk-compman-upgrade-guide.md index 02fdf8d544e..e002ce99f3e 100644 --- a/src/guides/v2.3/comp-mgr/bk-compman-upgrade-guide.md +++ b/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. + *[contributing developer]: A developer who contributes code to the Magento 2 CE codebase diff --git a/src/guides/v2.4/comp-mgr/bk-compman-upgrade-guide.md b/src/guides/v2.4/comp-mgr/bk-compman-upgrade-guide.md index 7b4079160b7..f0bc8a22531 100644 --- a/src/guides/v2.4/comp-mgr/bk-compman-upgrade-guide.md +++ b/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. + *[contributing developer]: A developer who contributes code to the Magento 2 CE codebase diff --git a/src/safe-upgrade-tool/developer.md b/src/safe-upgrade-tool/developer.md new file mode 100644 index 00000000000..0a16826271f --- /dev/null +++ b/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. diff --git a/src/safe-upgrade-tool/img/audience-sut.png b/src/safe-upgrade-tool/img/audience-sut.png new file mode 100644 index 00000000000..2ebcc9ee4e9 Binary files /dev/null and b/src/safe-upgrade-tool/img/audience-sut.png differ diff --git a/src/safe-upgrade-tool/img/mvp-diagram-v2.png b/src/safe-upgrade-tool/img/mvp-diagram-v2.png new file mode 100644 index 00000000000..cef850b526f Binary files /dev/null and b/src/safe-upgrade-tool/img/mvp-diagram-v2.png differ diff --git a/src/safe-upgrade-tool/img/mvp-diagram.png b/src/safe-upgrade-tool/img/mvp-diagram.png new file mode 100644 index 00000000000..ec72fa18b74 Binary files /dev/null and b/src/safe-upgrade-tool/img/mvp-diagram.png differ diff --git a/src/safe-upgrade-tool/install.md b/src/safe-upgrade-tool/install.md new file mode 100644 index 00000000000..cfa08f491b3 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/src/safe-upgrade-tool/introduction.md b/src/safe-upgrade-tool/introduction.md new file mode 100644 index 00000000000..7f22a78e232 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/src/safe-upgrade-tool/prerequisites.md b/src/safe-upgrade-tool/prerequisites.md new file mode 100644 index 00000000000..ab9b792141c --- /dev/null +++ b/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. diff --git a/src/safe-upgrade-tool/run.md b/src/safe-upgrade-tool/run.md new file mode 100644 index 00000000000..76b76fbd729 --- /dev/null +++ b/src/safe-upgrade-tool/run.md @@ -0,0 +1,137 @@ +--- +group: software-update-guide +title: Run the tool +ee_only: True +functional_areas: + - Upgrade +--- + +The Magento 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. + +The SUT identifies potential problems that must be fixed in your custom code before attempting to upgrade to a newer version of Magento. + +The tool returns a list of errors and warnings that you must address before upgrading to a new version of Magento. + +{:.bs-callout-warning} +At the moment this is an ALPHA version with limited scope, only validating PHP Magento APIs and GraphQL schema. + +## Use SUT + +Execute the tool by running the following command: + +```bash +bin/sut upgrade:check INSTALLATION_DIR +``` + +{:.bs-callout-info} +We recommend running `php -d memory_limit=-1 /bin/sut` to avoid memory limitations. As well, it is recommended to use the `-m` command to run the tool against a specific module. + +The `INSTALLATION_DIR` value is the directory where your Magento instance is located. + +To see SUT command options and help: + +```bash +bin/sut --help +``` + +### GraphQL schema compatibility verification + +The SUT also provides the option to introspect two GraphQL endpoints and compare their schemas looking for breaking and dangerous changes between them: + +```bash +bin/sut graphql:compare https://domain1.com/graphql https://domain2.com/graphql +``` + +You must have running "instance before" and "instance after" the upgrade. + +### Arguments and options + +#### Version + +You can compare your current Magento installation with Magento versions `>=2.3`. + +You must provide the version as a parameter when running the command: + +```bash +bin/sut upgrade:check INSTALLATION_DIR -c 2.4.1 +``` + +There are some limitations when running the previous command: + +* This parameter refers to any tag that identifies a specific version of Magento. +* It is a requirement to provide this one explicitly; providing only the value of it will not work. +* Provide the tag version without any quotation marks (neither single nor double): ~~'2.4.1-develop'~~. +* You should NOT provide older versions than the one you have currently installed, nor older than 2.3, which is the oldest one supported at the moment. + +#### Full report + +You can also get a full report containing both _PHP-related_ errors and GraphQL. In this case, you must provide at least the following options: + +* `--schema1=SCHEMA1` +* `--schema2=SCHEMA2` +* `INSTALLATION_DIR` + +#### Example of a bin/sut command + +```bash +bin/sut upgrade:check --schema1=https://domain1.com/graphql --schema2=https://domain2.com/graphql -c 2.4.1 INSTALLATION_DIR +``` + +### Output + +The SUT provides a report identifying the affected non-Magento modules and the severity and description of the problem for every issue encountered: + +#### Example with a list of errors/warnings + +```php +File: /app/code/Custom/CatalogExtension/Controller/Index/Index.php +------------------------------------------------------------------ + + * [ERROR] Line 84: Used nonexistent or non Magento API interface 'Magento\Catalog\Model\ProductRepositoryInterface' + * [WARNING] Line 6: Importing Magento @deprecated class 'Magento\Catalog\Model\ProductRepository' +``` + +The report also includes a detailed summary: + +* *Installed Version*: the version currently installed +* *Magento Version*: the version you want to upgrade to +* *Running time*: amount of time the analysis took to build the report (mm:ss) +* *Checked modules*: amount of modules installed in the current magento version examined during the analysis +* *PHP errors found*: amount of PHP errors +* *PHP warnings found*: amount of PHP warnings +* *GraphQL errors found*: amount of GraphQL errors +* *GraphQL warnings found*: amount of GraphQL warnings +* *Total errors found*: total amount of errors found +* *Total warnings found*: total amount of warnings found +* *Complexity score*: a figure that indicates how difficult is to upgrade from the current version to the new one + +The lower this number is, the easier is to perform the upgrade. + +#### Example of a summary report + +```php + ------------------------ -------- + Installed version 2.3.5 + Magento version 2.4.1 + Running time 0m:48s + Checked modules 60 + PHP errors found 162 + PHP warnings found 120 + GraphQL errors found 19 + GraphQL warnings found 0 + Total errors found 181 + Total warnings found 120 + Complexity score 482 + ------------------------ -------- +``` + +Regarding the GraphQL schema compatibility comparison, the output would be very similar: + +#### Example with a list of errors/warnings for GraphQL + +```php + * [ERROR] FIELD_CHANGED_KIND: ConfigurableProduct.gender changed type from Int to String. + * [WARNING] OPTIONAL_INPUT_FIELD_ADDED: An optional field sku on input type ProductAttributeSortInput was added. +``` + +See [Developer information]({{site.baseurl}}/safe-upgrade-tool/developer.html) for more information.