migrate-ease tech review

content/learning-paths/servers-and-cloud-computing/migrate-ease/1_codescanning.md

@@ -1,18 +1,18 @@
 ---
 # User change
-title: "Why Code Scanning Matters for Arm Migration"
+title: "Assess your code for migration to Arm"
 
 weight: 2
 
 layout: "learningpathall"
 
 ---
 
-### Overview of the Common Arm Migration Challenge
+### Common Arm Migration Challenges
 
-Migrating applications to Arm-based architectures is increasingly common across cloud, data center, and edge environments. Arm-powered servers and instances, such as AWS Graviton processors or Ampere Altra-based systems available on platforms like Google Cloud Platform, Microsoft Azure, Alibaba Cloud and Oracle Cloud Infrastructure (OCI), deliver significant performance-per-watt advantages and compelling cost-efficiency.
+Migrating applications to Arm-based architectures is increasingly common across cloud, data center, and edge environments. Arm-powered servers and instances, available in AWS, Gooogle Cloud Platform, Microsoft Azure, Alibaba Cloud and Oracle Cloud Infrastructure (OCI), deliver significant performance-per-watt advantages and compelling cost-efficiency.
 
-However, porting workloads to new CPU architecture often involves more than just recompiling. While many applications transition smoothly, others contain architecture-specific code or dependencies – developed originally for x86 – that can lead to build failures, runtime errors, or performance degradation on Arm systems.
+However, porting workloads to from one CPU architecture or another, can often require more than just recompilation. While many applications transition smoothly, others contain architecture-specific code or dependencies – developed originally for x86 – that can lead to build failures, runtime errors, or performance degradation on Arm systems.
 
 Common challenges include detecting:
 * Hardcoded x86 SIMD intrinsics
@@ -24,7 +24,7 @@ Common challenges include detecting:
 In large or legacy codebases, these issues are often buried in third-party libraries or auto-generated components, making manual inspection slow and unreliable.
 
 ### Automated Analysis for Portability
-To address these challenges proactively, automated static analysis tools play a critical role. Tools specifically designed for portability analysis enable developers to scan local codebases or remote repositories (e.g., GitHub) —and pinpoint architecture-specific constructs before attempting compilation or deployment on Arm. By surfacing portability concerns early in the development cycle, code scanning reduces time-to-first-build and helps prevent complex failures later.
+To address these challenges, static code analysis tools play a critical role. Tools specifically designed for portability analysis enable developers to scan local codebases or remote repositories (e.g., GitHub) —and pinpoint architecture-specific constructs before attempting compilation or deployment on Arm. By surfacing portability concerns early in the development cycle, code scanning reduces time-to-first-build and helps prevent complex failures later.
 
-In this learning path, we will introduce `migrate-ease`, a tool which allows developers to move beyond trial-and-error debugging. It provides clear, actionable insights into potential portability issues, detecting problematic patterns across many mainstream programming languages. These insights, combined with targeted refactoring, accelerate the process of making code portable, maintainable, and production-ready on Arm.
+In this learning path, you will learn about `migrate-ease`, a tool which allows developers to move beyond trial-and-error debugging to port their code to Arm. It provides clear, actionable insights into potential portability issues, detecting problematic patterns across many mainstream programming languages. These insights, combined with targeted refactoring, accelerate the process of making code portable, maintainable, and production-ready on Arm.
 

content/learning-paths/servers-and-cloud-computing/migrate-ease/2_migrate_ease_spec.md

@@ -8,22 +8,18 @@ layout: "learningpathall"
 
 ---
 
-### migrate-ease
+### What is migrate-ease?
 
-This is a fork of [Porting advisor](https://github.com/arm-hpc/porting-advisor), an open source project by the Arm engineering team. Migrate-ease is maintained by the [OpenAnolis](https://github.com/openanolis) Arm Working Group.
+[Migrate-ease](https://github.com/migrate-ease/) is a fork of [Porting advisor](https://github.com/arm-hpc/porting-advisor), an open-source project developed by Arm. Migrate-ease is maintained by the [OpenAnolis](https://github.com/openanolis) Arm Working Group.
 
 
-It is an innovative project designed to analyze codebases specifically for x86_64 architectures and offers tailored suggestions aimed at facilitating the migration process to aarch64. 
-This tool streamlines the transition, ensuring a smooth and efficient evolution of your software to leverage the benefits of aarch64 architecture. 
-At present, this tool only supports codebase migration to Linux. It can be run on Arm or non-Arm based machines. The tool does not modify any code, it does not provide API level recommendations, and it does not send any data back to OpenAnolis.
-
-{{% notice Note %}}
-Even though the [migrate-ease](https://github.com/migrate-ease/) project team does the best to identify known incompatibilities, that's still recommend performing appropriate tests on your application before going to Production.
-{{% /notice %}}
+It is designed to analyze codebases specifically for `x86_64` architectures and offers tailored suggestions to facilitate the migration process to aarch64. 
+At present, this tool only supports codebase migration to Linux. The tool can be run on Arm or `x86_64` Linux machines. The tool does not modify any code, it inspects your code and provides recommendations.
+It does not provide API level recommendations, and it does not send any data back to OpenAnolis.
 
 ### List of Supported Programming Languages
 
-This tool scans all files in a source tree, regardless of whether they are included by the build system or not. Currently, the tool supports the following languages/dependencies:
+This tool scans all files in a source tree, regardless of whether they are included by the build system or not. Currently, the tool supports the following languages/dependencies and the types of checks available for each launguage are shown:
 
 #### C, C++
 - Inline assembly with no corresponding aarch64 inline assembly
@@ -54,11 +50,11 @@ This tool scans all files in a source tree, regardless of whether they are inclu
 
 #### Java
 - JAR scanning
-- Dependency versions in pom.xml file
+- Dependency versions in `pom.xml` file
 - A feature to detect native calls in Java source code
-- Compatible version recommendation
+- Compatible version recommendations
 
 #### Dockerfile
 - Use of architecture specific plugin
-- The base image that dockfile is based on does not support aarch64
+- The base image that dockerfile is based on does not support aarch64
 

content/learning-paths/servers-and-cloud-computing/migrate-ease/3_migrate_ease_run.md

@@ -1,6 +1,6 @@
 ---
 # User change
-title: "Installing and Running Code Analysis Tools"
+title: "Install migrate-ease"
 
 weight: 4
 
@@ -10,15 +10,15 @@ layout: "learningpathall"
 
 # migrate-ease
 
-[migrate-ease](https://github.com/migrate-ease/migrate-ease) is an open-source project designed to analyze codebases specifically for x86_64 architectures and offers tailored suggestions aimed at facilitating the migration process to AArch64. This tool streamlines the transition, ensuring a smooth and efficient evolution of your software to leverage the benefits of aarch64 architecture.
+[migrate-ease](https://github.com/migrate-ease/migrate-ease) is an open-source project designed to analyze codebases specifically for `x86_64` architectures and offers tailored suggestions aimed at facilitating the migration process to AArch64. This tool streamlines the transition, ensuring a smooth and efficient evolution of your software to leverage the benefits of aarch64 architecture.
 
 ## Pre-requisites
-Before you use migrate-ease, certain pre-requesites need to be installed.
+Before you use `migrate-ease`, certain pre-requisites need to be installed:
 {{< tabpane code=true >}}
   {{< tab header="Ubuntu 22.04">}}
 sudo apt-get install -y python3 python3-pip python3-venv unzip libmagic1 git
   {{< /tab >}}
-  {{< tab header="Debian trixie">}}
+  {{< tab header="Debian 13">}}
 sudo apt-get install -y python3 python3-pip python3-venv unzip libmagic1 git
   {{< /tab >}}
   {{< tab header="Fedora 42">}}
@@ -27,59 +27,66 @@ sudo dnf install -y python3 python3-pip unzip git
 {{< /tabpane >}}
 
 ## Install and setup
-```bash
 
-# Check out the project
+Start by checking out the repository with the tool's source code:
+```bash
 git clone https://github.com/migrate-ease/migrate-ease
-
-# Check the project folder
 cd migrate-ease 
+```
 
-# Make sure you're at the root directory of migrate-ease
-# Enable Python Environment
+At the root directory of migrate-ease, create and activate a python virtual environment:
+```bash
 python3 -m venv .venv
 source .venv/bin/activate
+```
 
-# install python packages dependencies
+Install the python packages dependencies and set the environment variable to point to it:
+```bash
 pip3 install -r requirements.txt
-# Setup environment
 export PYTHONPATH=`pwd`
 ```
 
 ## Usage
-### As Python script
 
-User can scan a project with a scanner type and the result is sent to console by default.
+You are now ready to use `migrate-ease` on your source code. You can use the tool either from the command-line or using a Web GUI. 
+
+### Command-line usage
+
+From the command-line, you can use the tool to scan your local codebases with different programming languages. The result from the code analysis is sent to console by default.
+
 ```bash
 python3 -m {scanner_name} --arch {arch} {scan_path}
 ```
-Scan result can be exported as one of txt, csv, json or html.
+The result from the scan can also be exported as `txt`, `csv`, `json` or `html`. You will need to specify this using the `--output` option:
 
 To generate a JSON report:
 ```bash
 python3 -m {scanner_name} --output {result_file_name}.json --arch {arch} {scan_path}
 ```
 
+Here's an explanation of each of the arguments passed to the scanner tool:
+
 **Parameters**
 
-`{scanner_name}`: The name of the scanner, which can be one of cpp, docker, go, java, python, rust.
+`{scanner_name}`: The name of the scanner, which can be one of cpp, docker, go, java, python or rust.
 
-`{result_file_name}`: The name of the export result file (without the extension).
+`{result_file_name}`: The name of the exported results file (without the extension).
 
 `{arch}`: The architecture type, `aarch64` is the default.
 
 `{scan_path}`: The path to the code that needs to be scanned.
 
-User can scan a git repository as well by given the URL.
+You can scan a remote git repository code base as well by passing the URL as shown in the example:
 ```bash
 python3 -m {scanner_name} --output {result_file_name}.json --arch {arch} --git-repo {repo} {clone_path}
 ```
-In the case of git repository scan, `{clone_path}` is a directory to hold the cloned code. This directory should be empty or to be created.
+In the case of git repository scan, `{clone_path}` is a directory where the remote repo code is cloned into. This directory should be empty or must be created by the user.
 
-There are more parameters for user to control the scan behaviors. To get these information user can get the built-in help
+There are more parameters for user to control the scan functionality. To see this information, use the built-in help as shown:
 ```bash
 python3 -m {scanner_name} -h
 ```
+Replace {scanner_name} with either cpp, docker, go, java, python or rust.
 
 ### As Web UI
 Migrate-ease also provides a Web UI that supports scanning a git repo with cpp, docker, go, java, python and rust scanners in one time.

content/learning-paths/servers-and-cloud-computing/migrate-ease/4_migrate_ease_analysis.md

@@ -1,23 +1,23 @@
 ---
 # User change
-title: "Interpreting Analysis Results with a Real Example"
+title: "An example of running migrate-ease"
 
 weight: 5
 
 layout: "learningpathall"
 
 ---
-### Example from a real-world case
-[Protobuf](https://github.com/protocolbuffers/protobuf) is a widely used library for serializing structured data. AArch64 support is introduced in version v3.5.0 released in November 2017. Version v2.5.0 is a popular version without AArch64 support.
+### Example use case
+In this section, you will use the tool to scan the source code for [Protobuf](https://github.com/protocolbuffers/protobuf), a widely used library for serializing structured data. AArch64 support was Protobuf was introduced in version `v3.5.0` released in November 2017. For the purposes of demonstrating the usage of this tool, you will use an older version `v2.5.0` of Protobuf which lacks AArch64 support.
 
-Use migrate-ease to scan protobuf v2.5.0 with JSON result output:
-```
+Use `migrate-ease` to scan protobuf v2.5.0 and output the results to a JSON file named `result.json`:
+```bash
 python3 -m cpp --git-repo https://github.com/protocolbuffers/protobuf.git --branch v2.5.0 --output result.json --arch aarch64 protobuf
 ```
-A json file, `result.json`, will be generated in current directory once the scan is successfully executed.
+The output `result.json`, will be generated in your current directory once the scan is successfully executed.
 
-### How to read the result
-The JSON result is organized as following format:
+### How to interpret the results?
+Open the `result.json` file. You will see it is organized in the following format:
 ```output
 {
     "arch": "aarch64",
@@ -113,12 +113,11 @@ The JSON result is organized as following format:
     "total_issue_count": 14
 }
 ```
-The items in result are well self-explained along with their keys.
-User needs to check `issue_summary` and `issues` to uncover what potential problems are and suggested solutions.
+You will need to check `issue_summary` and `issues` for the potential porting to AArch64 problems along with the suggested solutions.
 
-The `issue_summary` provides an overview of the types of issues that the current scanner supports, along with the corresponding number of issues. For `cpp` scanner, the available issue types are:
+The `issue_summary` provides an overview of the types of issues that the current scanner supports, along with the corresponding number of issues found. 
 
-For each of programming Languages, the available issue types are:
+For each of the programming languages, the issue types are listed on the table:
 {{< tabpane code=true >}}
   {{< tab header="C++, C">}}
 Name                    | Description
@@ -185,12 +184,14 @@ Plugin             | A package used in RUN, CMD or ENTRYPOINT does not support A
   {{< /tab >}}
 {{< /tabpane >}}
 
-The `issues` is a list of those detected issues with details for each of them.
+The `issues` is a list of those detected issues with details for each:
 - `checkpoint`: A pattern to identify potential incompatibility.
 - `description`: The description of the detected issue.
 - `filename`: The file in which issue is detected.
 - `issue_type`: The type of issue, including detailed descriptions of the error.
 - `lineno`: The line number of the problematic code.
 - `snippet`: The block of the problematic code.
 
-For more information about issue type information perf review [migrate-ease github](https://github.com/migrate-ease/migrate-ease/blob/main/README.md).
+For more information about issue types refer to [migrate-ease github](https://github.com/migrate-ease/migrate-ease/blob/main/README.md).
+
+You have successfully learnt how to install and use the `migrate-ease` scanner tools. You can now use it to scan your source code repositories to identify compatibility issues for aarch64 and use the provided recommendations for porting your code to Arm.

content/learning-paths/servers-and-cloud-computing/migrate-ease/_index.md

@@ -1,20 +1,19 @@
 ---
-title: Accelerating Application Migration to Arm Servers Using Code Scanning Tools
+title: Migrate Applications to Arm Servers using migrate-ease
 
 draft: true
 cascade:
     draft: true
-    
+
 minutes_to_complete: 45
 
-who_is_this_for: This is an automated tool introductory for software developers and DevOps engineers who are preparing to migrate existing applications to Arm-based server environments. It introduces a static analysis tool (migrate-ease) that simplifies the process by identifying portability challenges early.
+who_is_this_for: This is an introductory topic for software developers looking to migrate their applications to Arm-based servers using a code analysis tool called migrate-ease. You can leverage this tool to scan source code repositories to identify porting issues you might encounter before migrating your code to run on Arm-based servers.
 
 
 learning_objectives:
-    - Set up an Arm development machine
-    - Analyze application source code for architecture-specific dependencies
-    - Understand common migration challenges and solutions
-    - Use migrate-ease to identify and prioritize portability issues
+    - Examine your application's source code for architecture-specific dependencies
+    - Understand common migration challenges and their corresponding solutions
+    - Use migrate-ease to detect and address AArch64 code portability concerns
 
 prerequisites:
     - An [Arm based instance](/learning-paths/servers-and-cloud-computing/csp/) from a cloud service provider.
@@ -42,10 +41,6 @@ further_reading:
         title: AWS Graviton Getting Started
         link: https://github.com/aws/aws-graviton-getting-started
         type: documentation
-    - resource:
-        title: AWS Graviton Processors
-        link: https://dev.to/aws-builders/aws-graviton-processors-3nk3
-        type: blog
     - resource:
         title: Arm Cloud Migration Program
         link: https://www.arm.com/markets/computing-infrastructure/arm-cloud-migration