diff --git a/docs/eclipse-code-ready-studio-guide/master.adoc b/docs/eclipse-code-ready-studio-guide/master.adoc index 3a78c1b442..90c3dcfe36 100644 --- a/docs/eclipse-code-ready-studio-guide/master.adoc +++ b/docs/eclipse-code-ready-studio-guide/master.adoc @@ -19,7 +19,8 @@ include::topics/making-open-source-more-inclusive.adoc[] [id="introduction_{context}"] == Introduction -include::topics/about-ide-addons.adoc[leveloffset=+2] +// Looking to move to new repo +include::topics/mta-about-ide-addons.adoc[leveloffset=+2] include::topics/mta-what-is-the-toolkit.adoc[leveloffset=+2] [id="installing-plugin_{context}"] @@ -27,25 +28,25 @@ include::topics/mta-what-is-the-toolkit.adoc[leveloffset=+2] You can install the {PluginName} in a connected or a restricted network environment. -include::topics/eclipse-installing-plugin.adoc[leveloffset=+2] +include::topics/mta-eclipse-installing-plugin.adoc[leveloffset=+2] :!eclipse-code-ready-studio-guide: :context: disconnected :disconnected: -include::topics/eclipse-installing-plugin.adoc[leveloffset=+2] +include::topics/mta-eclipse-installing-plugin.adoc[leveloffset=+2] :!disconnected: :context: eclipse-code-ready-studio-guide :eclipse-code-ready-studio-guide: -include::topics/eclipse-accessing-tools.adoc[leveloffset=+2] +include::topics/mta-eclipse-accessing-tools.adoc[leveloffset=+2] [id="analyzing-projects-with-plugin_{context}"] == Analyzing your projects with the {PluginName} You can analyze your projects with the {PluginName} by creating a run configuration, running an analysis, and then reviewing and resolving migration issues detected by the {PluginName}. -include::topics/eclipse-configuring-run.adoc[leveloffset=+2] -include::topics/eclipse-analyzing-projects.adoc[leveloffset=+2] -include::topics/eclipse-reviewing-issues.adoc[leveloffset=+2] -include::topics/eclipse-resolving-issues.adoc[leveloffset=+2] +include::topics/mta-eclipse-configuring-run.adoc[leveloffset=+2] +include::topics/mta-eclipse-analyzing-projects.adoc[leveloffset=+2] +include::topics/mta-eclipse-reviewing-issues.adoc[leveloffset=+2] +include::topics/mta-eclipse-resolving-issues.adoc[leveloffset=+2] // TODO: Uncomment when uninstalling works and this is ready // include::topics/plugin-uninstall.adoc[leveloffset=+1] @@ -57,9 +58,9 @@ The {PluginName} comes with a core set of *System* rules for analyzing projects You can create and import custom rulesets. -include::topics/eclipse-viewing-rules.adoc[leveloffset=+2] -include::topics/eclipse-creating-custom-ruleset.adoc[leveloffset=+2] -include::topics/eclipse-importing-custom-ruleset.adoc[leveloffset=+2] -include::topics/eclipse-submitting-ruleset.adoc[leveloffset=+2] +include::topics/mta-eclipse-viewing-rules.adoc[leveloffset=+2] +include::topics/mta-eclipse-creating-custom-ruleset.adoc[leveloffset=+2] +include::topics/mta-eclipse-importing-custom-ruleset.adoc[leveloffset=+2] +include::topics/mta-eclipse-submitting-ruleset.adoc[leveloffset=+2] :!eclipse-code-ready-studio-guide: diff --git a/docs/intellij-idea-plugin-guide/master.adoc b/docs/intellij-idea-plugin-guide/master.adoc index 3fd544f407..ec9bbd5c9e 100644 --- a/docs/intellij-idea-plugin-guide/master.adoc +++ b/docs/intellij-idea-plugin-guide/master.adoc @@ -20,28 +20,28 @@ include::topics/making-open-source-more-inclusive.adoc[] == Introduction // About the IntelliJ IDEA plugin -include::topics/about-ide-addons.adoc[leveloffset=+2] +include::topics/mta-about-ide-addons.adoc[leveloffset=+2] // About {ProductName} include::topics/mta-what-is-the-toolkit.adoc[leveloffset=+2] // Install the plugin -include::topics/installing-intellij-idea-plugin.adoc[leveloffset=+1] +include::topics/mta-installing-intellij-idea-plugin.adoc[leveloffset=+1] [id="analyzing-projects-with-idea-plugin"] == Analyzing your projects with the {ProductShortName} plugin You can analyze your projects with the {ProductShortName} plugin by creating a run configuration and running an analysis. -include::topics/intellij-idea-plugin-run-configuration.adoc[leveloffset=+2] +include::topics/mta-intellij-idea-plugin-run-configuration.adoc[leveloffset=+2] [id="reviewing-and-resolving-migration-issues"] == Reviewing and resolving migration issues You can review and resolve migration issues identified by the {ProductShortName} plugin in the left pane. -include::topics/intellij-idea-plugin-reviewing-issues.adoc[leveloffset=+2] +include::topics/mta-intellij-idea-plugin-reviewing-issues.adoc[leveloffset=+2] -include::topics/intellij-idea-plugin-resolving-issues.adoc[leveloffset=+2] +include::topics/mta-intellij-idea-plugin-resolving-issues.adoc[leveloffset=+2] :!idea-plugin: diff --git a/docs/topics/mta-about-ide-addons.adoc b/docs/topics/mta-about-ide-addons.adoc new file mode 100644 index 0000000000..0b2485e0de --- /dev/null +++ b/docs/topics/mta-about-ide-addons.adoc @@ -0,0 +1,21 @@ +// Module included in the following assemblies: +// +// * docs/vs-code-extension-guide/master.adoc +// * docs/intellij-idea-plugin-guide/master.adoc +// * docs/eclipse-code-ready-guide/master.adoc + +:_content-type: CONCEPT +[id="about-ide-addons_{context}"] += About the {ProductShortName} {AddonType} for {IDEName} + +You can migrate and modernize applications by using the {ProductName} ({ProductShortName}) {AddonType} for {IDEName}. + +The {ProductShortName} {AddonType} analyzes your projects using customizable rulesets, marks issues in the source code, provides guidance to fix the issues, and offers automatic code replacement, if possible. + +ifdef::vsc-extension-guide[] +The {ProductShortName} extension is also compatible with Visual Studio Codespaces, the Microsoft cloud-hosted development environment. +endif::[] + +ifdef::idea-plugin-guide[] +The {AddonType} supports both the Community Edition and the Ultimate version of {IDEName}. +endif::[] diff --git a/docs/topics/mta-eclipse-accessing-tools.adoc b/docs/topics/mta-eclipse-accessing-tools.adoc new file mode 100644 index 0000000000..379dbcf2ca --- /dev/null +++ b/docs/topics/mta-eclipse-accessing-tools.adoc @@ -0,0 +1,33 @@ +// Module included in the following assemblies: +// +// * docs/eclipse-code-ready-studio-guide/master.adoc + +:_content-type: PROCEDURE +[id="eclipse-accessing-tools_{context}"] += Accessing the {ProductShortName} tools + +You can access the {PluginName} tools in the *{ProductShortName}* perspective. + +.Prerequisites + +* You must restart the Eclipse IDE after installing the {PluginName}. + +.Procedure + +. Click *Window* -> *Perspective* -> *Open Perspective* -> *Other*. +. Select *{ProductShortName}* and click *OK*. ++ +The following components are displayed: + +* *Issue Explorer* displays the migration issues identified by the {PluginName}. +* *{ProductShortName} Server* is a separate process that analyzes projects, flags migration issues, and generates reports. ++ +You can start, stop, and view the status of the {ProductShortName} server in the *Issue Explorer*. + +* *Issue Details* displays detailed information about a selected issue, including the hint, severity, and any additional resources. +* *{ProductShortName} Report* is an HTML report generated by the {PluginName}. From the report landing page you can navigate to detailed reports, such as Application Details, Issues, and Dependencies. ++ +[NOTE] +==== +The report is not generated by default. You must select the *Generate Report* option in the run configuration. +==== diff --git a/docs/topics/mta-eclipse-analyzing-projects.adoc b/docs/topics/mta-eclipse-analyzing-projects.adoc new file mode 100644 index 0000000000..9dbf8a6a17 --- /dev/null +++ b/docs/topics/mta-eclipse-analyzing-projects.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +// * docs/eclipse-code-ready-studio-guide/master.adoc + +:_content-type: PROCEDURE +[id="eclipse-analyzing-projects_{context}"] += Analyzing projects + +You can analyze your projects by running the {PluginName} with a saved run configuration. + +.Procedure + +. In the *{ProductShortName}* perspective, click the *Run* button (image:run_exc.png[Run button]) and select a run configuration. ++ +The {PluginName} analyzes your projects. The *Issue Explorer* displays migration issues that are detected with the ruleset. + +. When you have finished analyzing your projects, stop the {ProductShortName} server in the *Issue Explorer* to conserve memory. diff --git a/docs/topics/mta-eclipse-configuring-run.adoc b/docs/topics/mta-eclipse-configuring-run.adoc new file mode 100644 index 0000000000..57e5d1df34 --- /dev/null +++ b/docs/topics/mta-eclipse-configuring-run.adoc @@ -0,0 +1,35 @@ +// Module included in the following assemblies: +// +// * docs/eclipse-code-ready-studio-guide/master.adoc + +:_content-type: PROCEDURE +[id="eclipse-configuring-run_{context}"] += Creating a run configuration + +You can create a run configuration in the *Issue Explorer*. A run configuration specifies the project to analyze, migration path, and additional options. + +You can create multiple run configurations. Each run configuration must have a unique name. + +.Prerequisite + +* You must import your projects into the Eclipse IDE. + +.Procedure + +. In the *Issue Explorer*, click the {ProductShortName} icon (image:Product_Icon-Migration_Toolkit-RGB.png[{ProductShortName} button]) to create a run configuration. +. On the *Input* tab, complete the following fields: +.. Select a migration path. +.. Beside the *Projects* field, click *Add* and select one or more projects. +.. Beside the *Packages* field, click *Add* and select one or more the packages. ++ +[NOTE] +==== +Specifying the packages for analysis reduces the run time. If you do not select any packages, all packages in the project are scanned. +==== + +. On the *Options* tab, you can select *Generate Report* to generate an HTML report. The report is displayed in the *Report* tab and saved as a file. ++ +Other options are displayed. See link:{ProductDocUserGuideURL}#cli-args_cli-guide[About {ProductShortName} command-line arguments] in the _{UserCLIBookName}_ for details. + +. On the *Rules* tab, you can select custom rulesets that you have imported or created for the {PluginName}. +. Click *Run* to start the analysis. diff --git a/docs/topics/mta-eclipse-creating-custom-ruleset.adoc b/docs/topics/mta-eclipse-creating-custom-ruleset.adoc new file mode 100644 index 0000000000..acfae9d2bc --- /dev/null +++ b/docs/topics/mta-eclipse-creating-custom-ruleset.adoc @@ -0,0 +1,31 @@ +// Module included in the following assemblies: +// +// * docs/eclipse-code-ready-studio-guide/master.adoc + +:_content-type: PROCEDURE +[id="eclipse-creating-custom-ruleset_{context}"] += Creating a custom ruleset + +You can create a custom ruleset in the *{ProductShortName}* perspective. + +See the link:{ProductDocRulesGuideURL}[_{RulesDevBookName}_] to learn more about creating custom XML rules. + +.Procedure + +. Click the *Rulesets* tab. +. Click the Create Ruleset icon (image:repository-new.gif[Create ruleset icon]). +. Select a project and a directory for the ruleset. +. Enter the file name. ++ +[NOTE] +==== +The file must have the extension `.windup.xml`. +==== + +. Enter a ruleset ID, for example, `my-ruleset-id`. +. Optional: Select *Generate quickstart template* to add basic rule templates to the file. +. Click *Finish*. +. The ruleset file opens in an editor and you can add and edit rules in the file. +. Click the *Source* tab to edit the XML source of the ruleset file. + +You can select the new ruleset when you create a run configuration. diff --git a/docs/topics/mta-eclipse-importing-custom-ruleset.adoc b/docs/topics/mta-eclipse-importing-custom-ruleset.adoc new file mode 100644 index 0000000000..02b2aab0e5 --- /dev/null +++ b/docs/topics/mta-eclipse-importing-custom-ruleset.adoc @@ -0,0 +1,23 @@ +// Module included in the following assemblies: +// +// * docs/eclipse-code-ready-studio-guide/master.adoc + +:_content-type: PROCEDURE +[id="eclipse-importing-custom-ruleset_{context}"] += Importing a custom ruleset + +You can import a custom ruleset into the {PluginName} to analyze your projects. + +.Prerequisites + +* Custom ruleset file with a `.windup.xml` extension. ++ +See the link:{ProductDocRulesGuideURL}[_{RulesDevBookName}_] for information about creating rulesets. + +.Procedure + +. Click the *Rulesets* tab. +. Click the Import Ruleset icon (image:import-repository.png[Import ruleset icon]). +. Browse to and select the XML rule file to import. ++ +The custom ruleset is displayed when you expand *Custom* on the *Rulesets* tab. diff --git a/docs/topics/mta-eclipse-installing-plugin.adoc b/docs/topics/mta-eclipse-installing-plugin.adoc new file mode 100644 index 0000000000..6442cafe5c --- /dev/null +++ b/docs/topics/mta-eclipse-installing-plugin.adoc @@ -0,0 +1,50 @@ +// Module included in the following assemblies: +// +// * docs/eclipse-code-ready-studio-guide/master.adoc + +:_content-type: PROCEDURE + +[id="eclipse-installing-plugin_{context}"] += Installing in a connected environment + +You need a connected environment to install the {PluginName}. + +The {PluginName} has been tested with the Eclipse IDE for Java Enterprise Developers 2023-03. + +.Prerequisites + +include::snippet_jdk-hardware-mac-prerequisites.adoc[leveloffset=0] + +* link:https://www.eclipse.org/downloads/packages/release/2023-03/r/eclipse-ide-java-developers[Eclipse IDE for Java Enterprise Developers 2023-03] +* JBoss Tools, installed from the link:https://marketplace.eclipse.org/content/jboss-tools[Eclipse Marketplace] +* link:http://download.eclipse.org/mylyn/releases/latest[Mylyn SDK and frameworks], installed with Eclipse + +[NOTE] +==== +Eclipse is pre-configured for Java 17, and the plugin operates directly with Java 17. + +You can also run the plugin with Java 11, which requires setting the JRE version to Java 11 when creating up a new Eclipse project or importing an existing one. See step 6 below. +==== + +.Procedure + +. Launch Eclipse. +. From the menu bar, select *Help* -> *Install New Software*. +. Next to the *Work with* field, click *Add*. +. In the *Name* field, enter `{ProductShortName}`. +. In the *Location* field, enter +ifdef::mtr[] +`https://marketplace.eclipse.org/content/migration-toolkit-runtimes-mtr` and click *OK*. +endif::[] +ifdef::mta[] +`https://marketplace.eclipse.org/content/migration-toolkit-applications-mta` and click *OK*. +endif::[] +. Select the Java version to use. +** If using Java 11, in the *JRE* list, select *JavaSE 11*. +** If using Java 17, leave the *JRE* selection unchanged. + +[start=7] +. Select all the *JBoss Tools - {ProductShortName}* check boxes and click *Next*. +. Review the installation details and click *Next*. +. Accept the terms of the license agreement and click *Finish*. +. Restart Eclipse. diff --git a/docs/topics/mta-eclipse-resolving-issues.adoc b/docs/topics/mta-eclipse-resolving-issues.adoc new file mode 100644 index 0000000000..98f3faca57 --- /dev/null +++ b/docs/topics/mta-eclipse-resolving-issues.adoc @@ -0,0 +1,15 @@ +// Module included in the following assemblies: +// +// * docs/eclipse-code-ready-studio-guide/master.adoc + +:_content-type: PROCEDURE +[id="eclipse-resolving-issues_{context}"] += Resolving issues + +You can resolve issues detected by the {PluginName} by performing one of the following actions: + +* You can double-click the issue to open it in an editor and edit the source code. ++ +The issue displays a Stale icon (image:stale_issue.gif[Stale]) until the next time you run the {PluginName}. +* You can right-click the issue and select *Mark as Fixed*. +* If the issue displays a Quick Fix icon (image:quickfix_error.png[Mandatory with quick fix] image:quickfix_info.png[Optional with quick fix] image:quickfix_warning.png[Warning with quick fix]), you can right-click the issue and select *Preview Quick Fix* and then *Apply Quick Fix*. diff --git a/docs/topics/mta-eclipse-reviewing-issues.adoc b/docs/topics/mta-eclipse-reviewing-issues.adoc new file mode 100644 index 0000000000..02f828e265 --- /dev/null +++ b/docs/topics/mta-eclipse-reviewing-issues.adoc @@ -0,0 +1,36 @@ +// Module included in the following assemblies: +// +// * docs/eclipse-code-ready-studio-guide/master.adoc + +:_content-type: PROCEDURE +[id="eclipse-reviewing-issues_{context}"] += Reviewing issues + +You can review issues identified by the {PluginName}. + +.Procedure + +. Click *Window* -> *Show View* -> *Issue Explorer*. +. Optional: Filter the issues by clicking the Options menu {kebab}, selecting *Group By* and an option. ++ +image::mta_group_by.png[Issue Explorer "Group By" options] + +. Right-click and select *Issue Details* to view information about the issue, including its severity and how to address it. ++ +The following icons indicate the severity and state of an issue: ++ +.Issue icons +[cols="20%a,80%",options="header",] +|==== +|Icon |Description +|image::error.png[Mandatory] |The issue must be fixed for a successful migration. +|image::info.gif[Optional] |The issue is optional to fix for migration. +|image::warning.png[Warning] |The issue might need to be addressed during migration. +|image::fixedIssue.gif[Resolved] |The issue was resolved. +|image::stale_issue.gif[Stale] |The issue is stale. The code marked as an issue was modified since the last time that {ProductShortName} identified it as an issue. +|image::quickfix_error.png[Mandatory with quick fix] |A quick fix is available for this issue, which is mandatory to fix for a successful migration. +|image::quickfix_info.png[Optional with quick fix] |A quick fix is available for this issue, which is optional to fix for migration. +|image::quickfix_warning.png[Warning with quick fix] |A quick fix is available for this issue, which may potentially be an issue during migration. +|==== + +. Double-click an issue to open the associated line of code in an editor. diff --git a/docs/topics/mta-eclipse-submitting-ruleset.adoc b/docs/topics/mta-eclipse-submitting-ruleset.adoc new file mode 100644 index 0000000000..74216132ab --- /dev/null +++ b/docs/topics/mta-eclipse-submitting-ruleset.adoc @@ -0,0 +1,22 @@ +// Module included in the following assemblies: +// +// * docs/eclipse-code-ready-studio-guide/master.adoc + +:_content-type: PROCEDURE +[id="eclipse-submitting-ruleset_{context}"] += Submitting a custom ruleset + +You can submit your custom ruleset for inclusion in the official {ProductShortName} rule repository. This allows your custom rules to be reviewed and included in subsequent releases of {ProductShortName}. + +.Procedure + +. Click the *Rulesets* tab. +. Click the Arrow icon (image:plugin-dropdown.png[Dropdown]) and select *Submit Ruleset*. +. Complete the following fields: + +* *Summary*: Describe the purpose of the rule. This becomes the title of the submission. +* *Code Sample*: Enter an example of the source code that the rule should run against. +* *Description*: Enter a brief description of the rule. + +. Click *Choose Files* and select the ruleset file. +. Click *Submit*. diff --git a/docs/topics/mta-eclipse-viewing-rules.adoc b/docs/topics/mta-eclipse-viewing-rules.adoc new file mode 100644 index 0000000000..49e8a1690f --- /dev/null +++ b/docs/topics/mta-eclipse-viewing-rules.adoc @@ -0,0 +1,21 @@ +// Module included in the following assemblies: +// +// * docs/eclipse-code-ready-studio-guide/master.adoc + +:_content-type: PROCEDURE +[id="plugin-viewing-rules_{context}"] += Viewing rules + +You can view system and custom rules, if any, for the {PluginName}. + +.Prerequisites + +* To view system rules, the {ProductShortName} server must be running. + +.Procedure + +. Click the *Rulesets* tab. +. Expand *System* to view system rulesets or *Custom* to view custom rulesets. +. Expand a ruleset. +. Double-click a rule to open it in a viewer. +. Click the *Source* tab to view the XML source of the rule. diff --git a/docs/topics/mta-installing-intellij-idea-plugin.adoc b/docs/topics/mta-installing-intellij-idea-plugin.adoc new file mode 100644 index 0000000000..f865f94a26 --- /dev/null +++ b/docs/topics/mta-installing-intellij-idea-plugin.adoc @@ -0,0 +1,22 @@ +// Module included in the following assemblies: +// +// * docs/intellij-idea-plugin-guide/master.adoc + +:_content-type: PROCEDURE +[id="intellij-idea-plugin-extension_{context}"] += Installing the {ProductShortName} plugin for IntelliJ IDEA + +You can install the {ProductShortName} plugin in the Ultimate and the Community Edition releases of IntelliJ IDEA. + +.Prerequisites +include::snippet_jdk-hardware-mac-prerequisites.adoc[] + +* The latest version of `{LC_PSN}-cli` from the link:{DevDownloadPageURL}[{ProductShortName} download page] + +.Procedure + +. In IntelliJ IDEA, click the *Plugins* tab on the Welcome screen. +. Enter `{ProductName}` in the Search field on the *Marketplace* tab. +. Select the *{ProductName} ({ProductShortName}) by Red Hat* plugin and click *Install*. ++ +The plugin is listed on the *Installed* tab. diff --git a/docs/topics/mta-installing-vs-code-extension.adoc b/docs/topics/mta-installing-vs-code-extension.adoc new file mode 100644 index 0000000000..0b10fd0496 --- /dev/null +++ b/docs/topics/mta-installing-vs-code-extension.adoc @@ -0,0 +1,27 @@ +// Module included in the following assemblies: +// +// * docs/vsc-extension-guide/master.adoc + +:_content-type: PROCEDURE +[id="installing-vs-code-extension_{context}"] += Installing the {ProductShortName} extension for Visual Studio Code + +You can install the {ProductShortName} extension for Visual Studio Code (VS Code). + +.Prerequisites +include::snippet_jdk-hardware-mac-prerequisites.adoc[] + +.Procedure + +. Set the environmental variable `JAVA_HOME`: ++ +[source, terminal,subs="attributes+"] +---- +$ export JAVA_HOME=jdk11 +---- + +. In VS Code, click the *Extensions* icon on the Activity bar to open the *Extensions* view. +. Enter `{ProductName}` in the Search field. +. Select the *{ProductName}* extension and click *Install*. ++ +The {ProductShortName} extension icon (image:vs_extension_icon.png[{ProductShortName} code extension]) is displayed on the Activity bar. diff --git a/docs/topics/mta-intellij-idea-plugin-resolving-issues.adoc b/docs/topics/mta-intellij-idea-plugin-resolving-issues.adoc new file mode 100644 index 0000000000..8e26f9ba0e --- /dev/null +++ b/docs/topics/mta-intellij-idea-plugin-resolving-issues.adoc @@ -0,0 +1,40 @@ +// Module included in the following assemblies: +// +// * docs/intellij-idea-plugin-guide/master.adoc + +[id="intellij-idea-plugin-resolving-issues_{context}"] += Resolving issues + +You can resolve issues by doing one of the following: + +* Using a _Quick Fix_ to fix a code snippet that has a hint +* Editing the code of a file that appears in a classification + +== Using a Quick Fix + +You can use a Quick Fix automatic code replacement to save time and ensure consistency in resolving repetitive issues. Quick Fixes are available for many issues displayed in the *Hints* section of the *Results* directory. + +.Procedure + +. In the left pane, click a hint that has an error indicator. ++ +Any Quick Fixes are displayed as child folders with the Quick Fix icon (image:intellij-idea-info.png[Quickfix]) on their left side. +. Right-click a Quick Fix and select *Preview Quick Fix*. ++ +The current code and the suggested change are displayed in the *Preview Quick Fix* window. +. To accept the suggested fix, click *Apply Quick Fix*. +. Optional: Right-click the issue and select *Mark As Complete*. ++ +A green check (image:intellij-idea-ok.png[Complete]) is displayed by the hint, replacing the error indicator. + +== Editing the code of a file + +You can directly edit a file displayed in the *Classifications* section of the *Results* directory. These files do not have any Quick Fixes. + +.Procedure + +. In the left pane, click the file you want to edit. +. Make any changes needed to the code and save the file. +. Optional: Right-click the issue and select *Mark as Complete* or *Delete*. ++ +If you select *Mark as Complete*, a green check (image:intellij-idea-ok.png[Complete]) is displayed by the hint, replacing the error indicator. diff --git a/docs/topics/mta-intellij-idea-plugin-reviewing-issues.adoc b/docs/topics/mta-intellij-idea-plugin-reviewing-issues.adoc new file mode 100644 index 0000000000..ee8359d40e --- /dev/null +++ b/docs/topics/mta-intellij-idea-plugin-reviewing-issues.adoc @@ -0,0 +1,29 @@ +// Module included in the following assemblies: +// +// * docs/intellij-idea-plugin-guide/master.adoc + +[id="intellij-idea-plugin-reviewing-issues_{context}"] += Reviewing issues + +You can use the {ProductShortName} plugin icons to prioritize issues based on their severity. You can see which issues have a _Quick Fix_ automatic code replacement and which do not. + +The results of an analysis are displayed in a directory format, showing the _hints_ and _classifications_ for each application analyzed. + +A _hint_ is a read-only snippet of code that contains a single issue that you should or must address before you can modernize or migrate an application. Often a Quick Fix is suggested, which you can accept or ignore. + +A _classification_ is a file that has an issue but does not have any suggested Quick Fixes. You can edit a classification. + +.Procedure + +. In the {ProductName} view, select a run configuration directory in the left pane. ++ +. Click *Results*. ++ +The modules and applications of the run configuration are displayed, with hints and classifications beneath each application. + +. Prioritize issues based on the following icons, which are displayed next to each hint: + +** image:intellij-idea-mandatory.png[Mandatory] : You must fix this issue in order to migrate or modernize the application. +** image:intellij-idea-potential.png[Warning] : You might need to fix this issue in order to migrate or modernize the application + +. Optional: To learn more about a hint, right-click it and select *Show More Details*. diff --git a/docs/topics/mta-intellij-idea-plugin-run-configuration.adoc b/docs/topics/mta-intellij-idea-plugin-run-configuration.adoc new file mode 100644 index 0000000000..d8da21b5b6 --- /dev/null +++ b/docs/topics/mta-intellij-idea-plugin-run-configuration.adoc @@ -0,0 +1,40 @@ +// Module included in the following assemblies: +// +// * docs/intellij-idea-plugin-guide/master.adoc + +[id="intellij-idea-plugin-run-configuration_{context}"] += Creating a run configuration + +You can create multiple run configurations to run against each project you import to IntelliJ IDEA. + +.Procedure + +. In the *Projects* view, click the project you want to analyze. +. On the left side of the screen, click the *{ProductName}* tab. ++ +If this is your first configuration, the run configuration panel is displayed on the right. + +. If this is not your first configuration, right-click configuration in the list and select *New configuration*. ++ +The run configuration panel is displayed on the right. + +. Complete the following configuration fields: + +** *cli*: Enter the path to the cli executable. For example: `$HOME/{LC_PSN}-cli-{ProductDistributionVersion}/bin/{mta-cli}`. +** *Input*: Click *Add* and enter the input file or directory. +** *Target*: Select one or more target migration paths. ++ +[NOTE] +==== +The location shown in the *Output* is set by the plugin. +==== + +. In the list of configurations, right-click the new configuration and select *Run Analysis*. ++ +The *Console ({ProductShortName})* terminal emulator opens, displaying information about the progress of the analysis. ++ +When the analysis is completed, you can click either *Report* or *Results* below the name of the configuration file you ran. + +** *Reports* opens the {ProductShortName} report, which describes any issues you need to address before you migrate or modernize your application. For more information, see link:{ProductDocUserGuideURL}#review-reports_cli-guide[Reviewing the reports] in the _{UserCLIBookName}_. + +** *Results* opens a directory displaying hints (issues) per application. diff --git a/docs/topics/mta-vs-code-extension-interface.adoc b/docs/topics/mta-vs-code-extension-interface.adoc new file mode 100644 index 0000000000..ab5a359d53 --- /dev/null +++ b/docs/topics/mta-vs-code-extension-interface.adoc @@ -0,0 +1,25 @@ +// Module included in the following assemblies: +// +// * docs/vsc-extension-guide/master.adoc + +:_content-type: CONCEPT +[id="vs-code-extension-interface_{context}"] += {ProductShortName} extension interface + + + +The interface of the {ProductName} ({ProductShortName}) extension is designed to make it easier for you to find information and perform actions: + +* In the left pane, you can see a directory tree named *Analysis Results* with a report icon at its top. You can click the icon to open the {ProductShortName} report in your browser. Beneath the report icon are the other elements of the tree: the applications analyzed by {ProductShortName}, the rulesets used, and the issues discovered by the analysis. +* In the upper right pane, you can configure an analysis. +* In the lower right pane, you can see the settings of the configuration, including source, target, and advanced options. You can view the progress of an analysis in this pane. When the analysis is completed, you can click the *Open Report* button to open the {ProductShortName} report, which describes any issues you need to address before you migrate or modernize your application. For more information, see link:{ProductDocUserGuideURL}#review-reports_cli-guide[Reviewing the reports] in the _{UserCLIBookName}_. + +.{ProductShortName} extension interface + +ifdef::mta[] + +endif::[] + +ifdef::mtr[] +image::mtr-extension-interface.png[{ProductShortName} extension interface] +endif::[] diff --git a/docs/topics/mta-vs-code-extension-resolving-issues.adoc b/docs/topics/mta-vs-code-extension-resolving-issues.adoc new file mode 100644 index 0000000000..8f52824d54 --- /dev/null +++ b/docs/topics/mta-vs-code-extension-resolving-issues.adoc @@ -0,0 +1,32 @@ +// Module included in the following assemblies: +// +// * docs/vsc-extension-guide/master.adoc + +:_content-type: PROCEDURE +[id="vs-code-extension-resolving-issues_{context}"] += Resolving issues + +You can resolve issues by editing the code of a file with a hint + + +//// + == Using a Quick Fix + +You can use a Quick Fix automatic code replacement to save time and ensure consistency in resolving repetitive issues. + +.Procedure + +. In the left pane, right-click an issue that has the Quick Fix icon (image:vs_optional.png[Optional or Quick Fix]) and select *Preview Quick Fix*. +. To accept the suggested fix, right-click the issue again and select *Apply Quick Fix.* +. Optional: Right-click the issue and select *Mark as Complete* or *Delete*. +//// + +== Editing the code of a file + +You can edit the file of a project imported to VS Code. + +.Procedure + +. In the left pane, right-click an issue and select *Open Code*. +. Make any changes needed to the code and save the file. +. Optional: Right-click the issue and select *Mark as Complete* or *Delete*. diff --git a/docs/topics/mta-vs-code-extension-reviewing-issues.adoc b/docs/topics/mta-vs-code-extension-reviewing-issues.adoc new file mode 100644 index 0000000000..cb91bf62dd --- /dev/null +++ b/docs/topics/mta-vs-code-extension-reviewing-issues.adoc @@ -0,0 +1,20 @@ +// Module included in the following assemblies: +// +// * docs/vsc-extension-guide/master.adoc + +:_content-type: PROCEDURE +[id="vs-code-extension-reviewing-issues_{context}"] += Reviewing issues + +You can use the {ProductShortName} extension icons to prioritize issues based on their severity. + +.Procedure + +. Select a run configuration directory on the left pane. +. Expand its folders to view the *Hints* generated for each application file. +. Select a hint to view the source code. +. Right-click a hint and select *View Details* to view the Rule ID and other information. +. Prioritize issues based on the following icons, which are displayed next to each hint: + +** image:vs_mandatory.png[Mandatory] : The issue must be fixed for a successful migration. +** image:vs_potential.png[Warning] : The issue might need to be addressed during migration. diff --git a/docs/topics/mta-vs-code-extension-run-configuration.adoc b/docs/topics/mta-vs-code-extension-run-configuration.adoc new file mode 100644 index 0000000000..de677ed999 --- /dev/null +++ b/docs/topics/mta-vs-code-extension-run-configuration.adoc @@ -0,0 +1,34 @@ +// Module included in the following assemblies: +// +// * docs/vsc-extension-guide/master.adoc + +:_content-type: PROCEDURE +[id="vs-code-extension-run-configuration_{context}"] += Configuring a run configuration + +You can configure multiple run configurations to run against each project you import to VS Code. + +.Prerequisites + +* `{mta-cli}` executable installed. You can download the `{mta-cli}` executable from link:{DevDownloadPageURL}[{LC_PSN} download]. + +.Procedure + +. In *Extensions* view, click the {ProductName} icon (image:vs_extension_icon.png[{ProductShortName} code extension]) on the Activity bar. +. Click the *+* (plus sign) next to *{ProductName}* to add a run configuration. +. Complete the following configuration fields: + +** *Name*: Enter a meaningful name for the analysis configuration or accept the default. + +** *cli*: Enter the path to the cli executable. For example: `$HOME/{mta-cli}-{ProductDistributionVersion}/bin/{mta-cli}`. + +** *Input*: Set to the path of the project that you have open within your IDE by clicking *Add* and doing one of the following: + +*** Enter the input file or directory and press Enter. +*** Click *Open File Explorer* and select the directory. + +** *Target*: Select one or more target migration paths. + +. Right-click the run configuration and select *Run*. ++ +When the analysis is completed, you can click the *Open Report* button to open the {ProductShortName} report, which describes any issues you need to address before you migrate or modernize your application. For more information, see link:{ProductDocUserGuideURL}#review-reports_cli-guide[Reviewing the reports] in the _{UserCLIBookName}_. diff --git a/docs/vs-code-extension-guide/master.adoc b/docs/vs-code-extension-guide/master.adoc index c9ea2b697c..bddff782df 100644 --- a/docs/vs-code-extension-guide/master.adoc +++ b/docs/vs-code-extension-guide/master.adoc @@ -18,31 +18,31 @@ include::topics/making-open-source-more-inclusive.adoc[] == Introduction // About the VS Code extension -include::topics/about-ide-addons.adoc[leveloffset=+2] +include::topics/mta-about-ide-addons.adoc[leveloffset=+2] // About {ProductName} include::topics/mta-what-is-the-toolkit.adoc[leveloffset=+2] // Install the extension -include::topics/installing-vs-code-extension.adoc[leveloffset=+1] +include::topics/mta-installing-vs-code-extension.adoc[leveloffset=+1] [id="analyzing-projects-with-vs-code-extension_{context}"] == Analyzing your projects with the {ProductShortName} extension You can analyze your projects with the {ProductShortName} extension by creating a run configuration and running an analysis. -include::topics/vs-code-extension-interface.adoc[leveloffset=+2] +include::topics/mta-vs-code-extension-interface.adoc[leveloffset=+2] -include::topics/vs-code-extension-run-configuration.adoc[leveloffset=+2] +include::topics/mta-vs-code-extension-run-configuration.adoc[leveloffset=+2] [id="reviewing-and-resolving-issues-with-vs-code-extension_{context}"] == Reviewing and resolving migration issues You can review and resolve migration issues identified by the {ProductShortName} extension in the left pane. -include::topics/vs-code-extension-reviewing-issues.adoc[leveloffset=+2] +include::topics/mta-vs-code-extension-reviewing-issues.adoc[leveloffset=+2] -include::topics/vs-code-extension-resolving-issues.adoc[leveloffset=+2] +include::topics/mta-vs-code-extension-resolving-issues.adoc[leveloffset=+2] :!vsc-extension-guide: