Merge pull request #763 from sbeskin-redhat/MTA_1220_fixed

MTA-1220 fixed

_config.yml

@@ -25,7 +25,7 @@ asciidoctor:
   - build=upstream
   - imagesdir=../topics/images
   - UserCLIBookName=CLI Guide
-  - RulesDevBookName=Rules Development Guide
+  - RulesDevBookName=Rule Development Guide
   - EclipseCrsGuideTitle=Eclipse and Red Hat CodeReady Studio Plugin Guide
   - IntroToMTABookName=Introduction to the Migration Toolkit for Applications
   - WebConsoleBookName=Web Console Guide

docs/rules-development-guide/master.adoc

@@ -24,81 +24,26 @@ include::topics/about-home-var.adoc[leveloffset=+3]
 // MTA Rules
 include::topics/about-rules.adoc[leveloffset=+2]
 
-// Getting Started
-include::topics/getting-started-rules.adoc[leveloffset=+1]
+== Creating YAML rules
 
-// Create Your First XML Rule
-include::topics/create-first-xml-rule.adoc[leveloffset=+2]
+Each analyzer rule is a set of instructions that are used to analyze source code and detect issues that are problematic for migration.
 
-// Review the Quickstarts
-include::topics/review-quickstarts.adoc[leveloffset=+2]
+The analyzer parses user-provided rules, applies them to applications' source code, and generates issues for matched rules. A collection of one or more rules forms a ruleset. Creating rulesets provides a way of organizing multiple rules that achieve a common goal. The analyzer CLI takes rulesets as input arguments.
 
-== Creating XML rules
+include::topics/yaml-rule-structure-syntax.adoc[leveloffset=+2]
 
-// XML Rule Structure
-include::topics/xml-rule-syntax.adoc[leveloffset=+2]
+=== Creating a basic YAML rule
 
-// Create a Basic XML Rule
-include::topics/create-basic-xml-rule.adoc[leveloffset=+2]
+This section describes how to create a basic {ProductShortName} YAML rule. This assumes that you already have {ProductShortName} installed. See the {ProductShortName} {ProductDocUserGuideURL}[_{UserCLIBookName}_] for installation instructions.
 
-=== XML rule syntax
+include::topics/create-basic-yaml-rule-template.adoc[leveloffset=+3]
 
-// When Condition Syntax
-include::topics/xml-rule-when-syntax.adoc[leveloffset=+3]
+include::topics/create-basic-yaml-ruleset-template.adoc[leveloffset=+3]
 
-// Perform Action Syntax
-include::topics/xml-rule-perform-syntax.adoc[leveloffset=+3]
+include::topics/create-yaml-rule.adoc[leveloffset=+3]
 
-// Where Syntax
-include::topics/where-syntax.adoc[leveloffset=+3]
+include::topics/running-analysis-using-custom-yaml-rule.adoc[leveloffset=+3]
 
-// Add the Rule to {ProductName}
-include::topics/add-rule-to-mta.adoc[leveloffset=+2]
+// Create Your First YAML Rule
+include::topics/create-first-yaml-rule.adoc[leveloffset=+2]
 
-// Testing XML Rules
-include::topics/testing-rules.adoc[leveloffset=+1]
-
-// Manually Test the XML Rule
-include::topics/manually-test-rules.adoc[leveloffset=+2]
-
-// Test the Rules Using JUnit
-include::topics/rules-testing-junit.adoc[leveloffset=+2]
-
-// About the validation report
-include::topics/validation-report.adoc[leveloffset=+2]
-
-// creating a Validation Report
-include::topics/validation-report-understanding.adoc[leveloffset=+3]
-
-// Reported Errors when Running the Validation Report
-include::topics/validation-report-errors.adoc[leveloffset=+3]
-
-// Overriding Rules
-include::topics/overriding-rules.adoc[leveloffset=+1]
-
-// Using Custom Rule Categories
-include::topics/rule-categories.adoc[leveloffset=+1]
-
-[appendix]
-== Reference material
-
-// Rule Story Points
-include::topics/about-story-points.adoc[leveloffset=+2]
-
-For more information on categorizing tasks, see xref:rule-categories_{context}[Using custom rule categories].
-
-=== Additional resources
-
-// Review the Existing MTA XML Rules
-include::topics/review-existing-rules.adoc[leveloffset=+3]
-
-// Fork and Clone the Ruleset GitHub Project
-include::topics/fork-ruleset-repo.adoc[leveloffset=+4]
-
-// Important Links
-include::topics/rules-important-links.adoc[leveloffset=+3]
-
-// **********************************
-// * Appendix: Revision Information *
-// **********************************
-include::topics/templates/revision-info.adoc[]

docs/topics/about-rules.adoc

@@ -7,19 +7,19 @@
 [id="about-rules_{context}"]
 = About {ProductShortName} rules
 
-The {ProductName} ({ProductShortName}) contains rule-based migration tools that analyze the APIs, technologies, and architectures used by the applications you plan to migrate. In fact, the {ProductShortName} analysis process is implemented using {ProductShortName} rules. {ProductShortName} uses rules internally to extract files from archives, decompile files, scan and classify file types, analyze XML and other file content, analyze the application code, and build the reports.
+The {ProductName} ({ProductShortName}) contains rule-based migration tools (analyzers) that analyze the APIs, technologies, and architectures used by the applications you plan to migrate. {ProductShortName} uses analyzer rules internally to extract files from archives, decompile files, scan and classify file types, analyze XML and other file content, analyze the application code, and build the reports.
 
 {ProductShortName} builds a data model based on the rule execution results and stores component data and relationships in a graph database, which can then be queried and updated as needed by the migration rules and for reporting purposes.
 
 {ProductShortName} rules use the following rule pattern:
 
 ----
 when(condition)
-  perform(action)
-otherwise(action)
+ message(message)
+ tag(tags)
 ----
 
-{ProductShortName} provides a comprehensive set of standard migration rules out-of-the-box. Because applications may contain custom libraries or components, {ProductShortName} allows you to write your own rules to identify use of components or software that may not be covered by the existing ruleset.
+Although {ProductShortName} provides a comprehensive set of standard migration rules out-of-the-box, you can create your own custom analyzer rules as well. You can use custom rules to identify use of custom libraries or other components that might not be covered by the provided out-of-the-box rulesets.
 
 ifndef::rules-development-guide[]
 If you plan to write your own custom rules, see the {ProductDocRulesGuideURL}[_{RulesDevBookName}_] for detailed instructions.

docs/topics/create-basic-yaml-rule-template.adoc

@@ -0,0 +1,42 @@
+// Module included in the following assemblies:
+//
+// * docs/rules-development-guide/master.adoc
+
+:_content-type: PROCEDURE
+[id="create-basic-yaml-rule-template_{context}"]
+= Creating a basic YAML rule template
+
+{ProductShortName} YAML-based rules have the following basic structure:
+
+[source,terminal]
+----
+when(condition)
+ message(message)
+ tag(tags)
+----
+.Procedure
+
+. In the `/home/<USER>/` directory, create a file containing the basic syntax for YAML rules as follows:
++
+[source,terminal]
+----
+- category: mandatory
+  description: |
+   <DESCRIPTION TITLE>
+   <DESCRIPTION TEXT>
+  effort: <EFFORT>
+  labels:
+  - konveyor.io/source=<SOURCE_TECH>
+  - konveyor.io/target=<TARGET_TECH>
+  links:
+ - url: <HYPERLINK>
+   title: <HYPERLINK_TITLE>
+  message: <MESSAGE>
+  tag:
+  - <TAG1>
+  - <TAG2>
+  ruleID: <RULE_ID>
+  when:
+   <CONDITIONS>
+----
+

docs/topics/create-basic-yaml-ruleset-template.adoc

@@ -0,0 +1,24 @@
+// Module included in the following assemblies:
+//
+// * docs/rules-development-guide/master.adoc
+
+:_content-type: PROCEDURE
+[id="create-basic-yaml-ruleset-template_{context}"]
+= Creating a basic YAML ruleset template
+
+If you want to group multiple similar rules, you can create a ruleset for them by placing their files in a directory and creating a `ruleset.yaml` file at the directory's root. When you pass this directory as input to the {ProductShortName} {CLIName} using the `--rules` option, {ProductShortName} treats all the files in the directory as belonging to the ruleset defined in the `ruleset.yaml` file.
+
+.Procedure
+
+. Create a template for `ruleset.yaml` files if you want to pass the entire directory using the `--rules` option:
++
+[source,terminal]
+----
+name: <RULESET_NAME> <1>
+description: <RULESET_DESCRIPTION>
+labels: <2>
+  - key=val
+----
+<1> The name must be unique within the provided rulesets.
++
+<2> Ruleset labels are inherited by all rules that belong to the ruleset.