Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

MTA-2744 - Rework MTA CLI section #880

Open
wants to merge 56 commits into
base: main
Choose a base branch
from

Conversation

HagayVider1
Copy link
Contributor

@HagayVider1 HagayVider1 commented May 6, 2024

Jira:

Preview

Goal

  • Restructure, clarify and modernize entire MTA CLI Guide
  • Update CLI installation procedure
  • Update podman installation procedure
  • Fill in missing sections and rewrite unclear sections

Copy link

netlify bot commented May 6, 2024

Deploy Preview for windup-documentation ready!

Name Link
🔨 Latest commit c2d899e
🔍 Latest deploy log https://app.netlify.com/sites/windup-documentation/deploys/665855405c1e0c0008177ea5
😎 Deploy Preview https://deploy-preview-880--windup-documentation.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

@anarnold97
Copy link
Collaborator

@HagayVider1 - you have worked on this locally and then not rebased to include the latest version. So when you created this branch, you created it from an outdated version of main.

Please rebase your local branch

Latest Version Your version
image image

HagayVider1 and others added 4 commits May 7, 2024 17:19
Co-authored-by: Andy Arnold <[email protected]>
I don't agree with removing the comma. This sentence should have a pause here.

Co-authored-by: Andy Arnold <[email protected]>
.idea/
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why have you changed the .gitignore file?
You should be using your global .gitignore file which we set up in our last git training session.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You have closed this comment and failed to correct your mistake

Copy link
Contributor Author

@HagayVider1 HagayVider1 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please note the comments that I added describing the decisions to change the document.

The PR cannot produce a preview, so I am attaching an HTML file of the document in the Jira ticket.

@@ -16,29 +16,26 @@ include::topics/making-open-source-more-inclusive.adoc[]

== Introduction

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reorganized sections in guide:
Making open source more inclusive

  1. Introduction
    1.1 About Migration Toolkit for Applications
    1.2 About the MTA CLI
    1.3 About the CLI guide
  2. Installing the CLI application
    2.1 Installing the CLI .zip file
    2.2 Installing the CLI using Podman
    2.3 Installation known issues
  3. Running the CLI
    3.1 Running the CLI
    3.2 MTA command syntax and examples
    3.3 Migration analysis using the command line
    3.4 Transformation using the CLI
  4. Reports
    4.1 Reviewing reports
    4.1.1 Application report
    4.1.2 Technologies report
    4.2 Selecting packages

@@ -4,11 +4,11 @@

:_content-type: PROCEDURE
[id="access-report_{context}"]
= Accessing reports
= Reports
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changed section on opening an analysis report be chapter header.

docs/topics/installing-cli-tool.adoc Outdated Show resolved Hide resolved
docs/topics/installing-cli-tool.adoc Outdated Show resolved Hide resolved
docs/topics/mta-what-is-the-toolkit.adoc Show resolved Hide resolved
[id="installing-downloadable-cli-zip_{context}"]
== Installing the {CLINameTitle} `.zip` file

.Procedure

To install using the downloadable `.zip` file:

. Navigate to the link:{DevDownloadPageURL}[{ProductShortName} Download page] and download the OS-specific CLI file or the `src` file:
. Navigate to the link:https://developers.redhat.com/products/mta/download[{ProductShortName} Download page] and download the OS-specific {ProductShortName} CLI file or the `mta-{ProductVersion}-cli-src` file:
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added link to MTA CLI download page with all OS download options

@@ -17,12 +17,12 @@ $ <{ProductShortName}_HOME>/bin/{mta-cli} --input /home/username/{mta-cli}-sourc
----
endif::cli-guide[]

Use a browser to open the `index.html` file located in the report output directory. This opens a landing page that lists the applications that were processed. Each row contains a high-level overview of the story points, number of incidents, and technologies encountered in that application.
Use a browser to open the `index.html` file located in the report output directory. This opens a landing page that lists the applications that were processed. Each row contains a high-level overview of the story points, number of incidents, and technologies encountered in that application.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The MTA analysis produces a static HTML file that shows the all the issues in the application. This is the same result as an analysis in the MTA Web Console, which should also cover the MTA report.
Should I insert or link/xref to sections in the MTA Web Console guide regarding MTA reports?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes please

@@ -24,24 +23,52 @@ Podman provides a command-line interface (CLI) familiar to anyone who has used t
For more information on installing and using Podman, see link:https://podman.io/docs/installation[Podman installation instructions].
====

.Installation options

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

New step on Installation options
Downloading the ZIP file is preferred, but installing using Podman is also available.

* {ProductShortNameLower}-{ProductVersion}-cli-src.zip
[NOTE]
====
Do not download and install the {ProductShortName} source code file if your computer runs one of the above operating systems.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

New note

@@ -4,15 +4,15 @@

:_content-type: PROCEDURE
[id="cli-run_{context}"]
= Running the {CLINameTitle}
// = Running the {CLINameTitle}
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Section upgraded to chapter heading

Copy link

@abrugaro abrugaro left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some minor changes


. Extract the `.zip` file to a directory of your choice. The `.zip` file extracts a single binary, called *mta-cli*.
+
When you encounter `<{ProductShortName}_HOME>` in this guide, replace it with the actual path to your {ProductShortName} installation.

. Copy or save the `mta-cli` binary on Linux, `darwin-mta-cli on macOS, or `mta-cli.exe` on Windows, to a known directory.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nitpick: backtick missing after "darwin-mta-cli"

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Corrected


You can run {ProductShortName} against your application.

.Procedure

. Open a terminal and navigate to the `<{ProductShortName}_HOME>/` directory.

. Execute the `{mta-cli}` script, or `{mta-cli}.exe` for Windows, and specify the appropriate arguments:
. Run the `{mta-cli}` script, or `{mta-cli}.exe` for Windows, or darwin-{mta-cli} for macOS, and specify the appropriate arguments:
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nitpick: missing backticks around "darwin-{mta-cli}"

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Corrected

@@ -22,13 +22,13 @@ The output directory contains the following files and subdirectories:

.Procedure

. Obtain the path of the `index.html` file of your report from the output that appears after you run {ProductShortName}:
. In the `<APPLICATION_NAME>-output` directory that you specified in the {ProductShortName} `./analyze` command, open the `index.html` file:
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is the ./ needed in this line?

Same question for line 9

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I ran the command with ./ at the beginning, and it generated the -output directory inside the directory where I was working.
MTA-CLI-command
The command created the <ApplicationName>-output directory.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Corrected line 9

Copy link
Contributor Author

@HagayVider1 HagayVider1 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Queries regarding images in static HTML output from MTA CLI

.Shared archives
image::3-2-shared-archives.png[Shared archives]
// .Shared archives
// image::3-2-shared-archives.png[Shared archives]
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

MTA does not produce any Issues for the JEE example application.
@abrugaro Is there a test application that I can run that produces issues, shared archives, etc?

If an application has dependencies, clicking the *Dependencies* tab to see a list of the application's dependencies.

.Dependencies
image::3-2-a-dependencies.png[Dependencies]
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@abrugaro
I added this section for the Dependencies tab.
Does it belong here?


.Dependencies
image::3-2-a-dependencies.png[Dependencies]

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@abrugaro
See .Dashboard below
The Dashboard does not show any issues. Is there a sample application I can analyze that MTA will show issues?

@@ -71,6 +71,7 @@ The dashboard gives an overview of the entire application migration effort. It s

.Dashboard
image::3-3-dashboard.png[Dashboard]
// The image I have from the static HTML file does not show any Issues or Share archives. Is there a sample application that I can run that shows these?
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The image from my static HTML file does not show any issues in the Dashboard.
Is there a sample application that an analysis will produce issues, shared archives, etc?

.idea/
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
.idea/
.idea/

Copy link
Collaborator

@anarnold97 anarnold97 Jun 15, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This image appears in MTA and MTR. Therefore you need to amend only for MTA, as your change means that MTR is wrong

/home/anarnold/Documents/SublimeMerge/windup-documentation/topics/mta-review-reports.adoc:
   66  
   67  .Dashboard
   68: image::3-3-dashboard.png[Dashboard]
   69  
   70  The top navigation bar lists the various reports that contain additional details about the migration of this application. Note that only those reports that are applicable to the current application will be available.
/home/anarnold/Documents/SublimeMerge/windup-documentation/topics/review-reports.adoc:
   66  
   67  .Dashboard
   68: image::3-3-dashboard.png[Dashboard]
   69  
   70  The top navigation bar lists the various reports that contain additional details about the migration of this application. Note that only those reports that are applicable to the current application will be available.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You have not checked where this image is used. It is used in MTA and MTR. You change corrects MTA but is incorrect for MTR

/home/anarnold/Documents/SublimeMerge/windup-documentation/topics/mta-review-reports.adoc:
   21  
   22  .Application list
   23: image::3-1-applications.png[Application list]
   24  
   25  NOTE: The incidents and estimated story points change as new rules are added to {ProductShortName}. The values here may not match what you see when you test this application.
/home/anarnold/Documents/SublimeMerge/windup-documentation/topics/review-reports.adoc:
   21  
   22  .Application list
   23: image::3-1-applications.png[Application list]
   24  
   25  NOTE: The incidents and estimated story points change as new rules are added to {ProductShortName}. The values here may not match what you see when you test this application.

* {ProductShortNameLower}-{ProductVersion}-cli-src.zip
[NOTE]
====
Do not download and install the {ProductShortName} source code file if your computer runs one of the above operating systems.
Copy link
Collaborator

@anarnold97 anarnold97 Jun 15, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You need to use Vale

💡 RedHat.TermsSuggestions 1(101-106) Depending on the context, consider using 'earlier', 'previous', 'preceding', or 'before' rather than 'above'.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants