WIP MTA-2257: Diverging MTA documentation

docs/eclipse-code-ready-studio-guide/master.adoc

@@ -19,33 +19,34 @@ 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}"]
 == Installing the {PluginName}
 
 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:

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:

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::[]

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.
+====

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.

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.

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.

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.

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.

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

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.

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