7/23/24 - ritz303 : Added a KI to README, plus a few minor edits

CHANGELOG.md

@@ -6,13 +6,16 @@
 - enhancement - Added support for private GitHub Registries.
 - fixes - Fixed an issue by removing a redundant `/` at the beginning of Windows URI paths that was causing some `mvn` commands to fail. See [PR#692](https://github.com/fabric8-analytics/fabric8-analytics-vscode-extension/pull/692) for details.
 - fixes - Fixed an issue with the Stack Analysis running on an open file, instead of running on an opened manifest file. See [PR#692](https://github.com/fabric8-analytics/fabric8-analytics-vscode-extension/pull/692) for details.
+- known issue - You can get an error by using the `Use Pip Dep Tree` and `Use Python Virtual Environment` options simultaneously. See the [Known Issues section](README.md#known-issues) of the README for more information.
+- known issue - Red Hat Dependency Analytics has limitations for Maven and Gradle. See the [Known Issues section](README.md#known-issues) of the README for more information.
+- known issue - Package version mismatch between the API response and the HTML report. See the [Known Issues section](README.md#known-issues) of the README for more information.
 - informational - Added a telemetry event to track Red Hat's recommended version acceptance.
 ## 0.9.4 (Mar 25th 2024)
 - informational - Removing access to Snyk's Vulnerability Database.
 ## 0.9.3 (Mar 6th 2024)
 - enhancement - Red Hat Dependency Analytics reporting has integrated the ONGuard service by using [Open Source Vulnerability (OSV)](https://google.github.io/osv.dev/) and the [National Vulnerability Database (NVD)](https://nvd.nist.gov/) data sources for additional vulnerability information.
 - enhancement - Integrated VS Code's [Secret Storage](https://code.visualstudio.com/api/references/vscode-api#SecretStorage) feature for securing the Snyk token. See [PR#689](https://github.com/fabric8-analytics/fabric8-analytics-vscode-extension/pull/689) for details.
-- fixes - Fixed an issue with displaying wrong data when the event handler for Component Analysis was triggered on a unsaved manifest file. Component Analysis is no longer triggered on unsaved manifest files. See [PR#239](https://github.com/fabric8-analytics/fabric8-analytics-lsp-server/pull/239) for details.
+- fixes - Fixed an issue with displaying wrong data when triggering the event handler for Component Analysis on a unsaved manifest file. Component Analysis is no longer triggered on unsaved manifest files. See [PR#239](https://github.com/fabric8-analytics/fabric8-analytics-lsp-server/pull/239) for details.
 - fixes - Fixed an issue where the diagnostic source name is being obscured in the View Problem panel from an inline analysis. See [PR#239](https://github.com/fabric8-analytics/fabric8-analytics-lsp-server/pull/239) for details.
 - informational - The naming convention for VS Code commands has changed from `fabric8` to `rhda`. For example, `fabric8.stackAnalysis` is now `rhda.stackAnalysis`.
 ## 0.9.2 (Feb 5th 2024)

README.md

@@ -22,11 +22,14 @@ In future releases, Red Hat plans to support other programming languages.
 	- [Configuration](#configuration)
 		- [Configurable parameters](#configurable-parameters)
 	- [Features](#features)
-	- [Known Issues](#known-issues)
 	- [Using Red Hat Dependency Analytics for CI builds](#using-red-hat-dependency-analytics-for-ci-builds)
-	- [Know more about the Red Hat Dependency Analytics platform](#know-more-about-the-red-hat-dependency-analytics-platform)
 	- [Data and telemetry](#data-and-telemetry)
+	- [Known issues](#known-issues)
+		- [Error when using options the `Use Pip Dep Tree` and `Use Python Virtual Environment` simultaneously](#error-when-using-options-the-use-pip-dep-tree-and-use-python-virtual-environment-simultaneously)
+		- [Red Hat Dependency Analytics limitations for Maven and Gradle](#red-hat-dependency-analytics-limitations-for-maven-and-gradle)
+		- [Package version mismatch between the API response and the HTML report](#package-version-mismatch-between-the-api-response-and-the-html-report)
 	- [Support, feedback \& questions](#support-feedback--questions)
+	- [Learn more about the Red Hat Dependency Analytics platform](#learn-more-about-the-red-hat-dependency-analytics-platform)
 	- [License](#license)
 
 ## Quick start
@@ -298,24 +301,36 @@ The default path is `/tmp/redhatDependencyAnalyticsReport.html`.
 	Doing this allows Red Hat Dependency Analytics to install Python packages into a virtual environment to perform the analysis.
 	The benefit is having a clean Python environment not influenced by earlier installations, but the downside is a significantly slower analysis process.
 
-## Known Issues
+## Known issues
 
-### Issue: Error when using options "Use Pip Dep Tree" and "Use Python Virtual Environment" simultaneously
+### Error when using options the `Use Pip Dep Tree` and `Use Python Virtual Environment` simultaneously
 
-In the `Python` ecosystem, when selecting both `Use Pip Dep Tree` and `Use Python Virtual Environment` options simultaneously, the application throws an error because pipdeptree is not configured in the virtual environment's Python interpreter.
+<br >In the Python ecosystem, when selecting both `Use Pip Dep Tree` and `Use Python Virtual Environment` options simultaneously, the application gives an error because `pipdeptree` is not configured for the Python's virtual environment.
 
-Furthermore, there is no practical value in using both configurations together. The primary goal of the `Use Pip Dep Tree` option is to optimize performance for Python version 3.11 and higher. On the other hand, the `Use Python Virtual Environment` option naturally works much slower than running in a local environment because installations are performed within the virtual environment.
+<br >Furthermore, there is no practical value in using both configurations together.
+Since these options contradict each other, the expected function of the `Use Pip Dep Tree` option has not effect when used with the `Use Python Virtual Environment` option.
+The primary goal of the `Use Pip Dep Tree` option is to optimize performance for Python version 3.11 and later.
+However, the `Use Python Virtual Environment` option works much slower than running in a local environment, because installations happen within the virtual environment.
+Red Hat recommends only using one of these options, depending on your specific requirements, but not both simultaneously.
 
-Since these options contradict each other, the expected function of the `Use Pip Dep Tree` option will be neutralized. It is recommended to use either one of these options, depending on your specific requirements, but not both simultaneously.
+### Red Hat Dependency Analytics limitations for Maven and Gradle
 
-### Issue: Dependency Analysis Limitations for Maven and Gradle
+<br >When a manifest includes dependencies with the `provided` scope in `Maven` or the `compileOnly` and `compileOnlyApi` configurations in `Gradle`, RHDA might not reliably detect vulnerabilities for these dependencies.
+This is due to the nature of the scopes and configurations where the version of the dependency used during the build process might not necessarily match the version used at runtime.
+This discrepancy occurs because the dependency is not packaged within the application's JAR file, meaning that the runtime environment must supply the necessary artifacts. This can lead to two potential issues:
 
-When a manifest includes dependencies with the `provided` scope in `Maven` or the `compileOnly` and `compileOnlyApi` configurations in `Gradle`, RHDA may not reliably detect vulnerabilities for these dependencies. This is due to the nature of these scopes and configurations where the version of the dependency used during the build process may not necessarily match the version used at runtime. This discrepancy occurs because the dependency is not packaged within the application's JAR file, meaning that the runtime environment must supply the necessary artifacts. This can lead to two potential issues:
+* `ClassNotFoundException`: If the runtime environment lacks the required artifacts on its `classpath`, the application will fail to run due to missing classes.
+* `Version Mismatch`: If the runtime environment provides different versions of the artifacts, it can cause application crashes, unexpected security vulnerabilities, or false positives in RHDA vulnerability scans.
 
-* ClassNotFoundException: If the runtime environment lacks the required artifacts on its classpath, the application will fail to run due to missing classes.
-* Version Mismatch: If the runtime environment provides different versions of the artifacts, it can cause application crashes, unexpected security vulnerabilities, or false positives in RHDA vulnerability scans.
+<br >Ensure your runtime environment includes the correct versions of these dependencies to avoid such issues.
 
-It is up to the users to ensure the runtime environment includes the correct versions of these dependencies to avoid such issues.
+### Package version mismatch between the API response and the HTML report
+
+<br >Opening a manifest file for analysis can give you a different package version number between the RHDA HTML report and an API client response.
+Before analyzing the manifest file, the API client compares package versions in the manifest file to the installed package versions within the client's environment.
+When there is a difference in package version, you receive an error message containing the first package version mismatch.
+To workaround this issue, you can disable the `Match Manifest Versions` option of RHDA.
+By disabling this option, RHDA will ignore all package version differences.
 
 ## Using Red Hat Dependency Analytics for CI builds
 
@@ -325,7 +340,7 @@ Red Hat offers integration with these Continuous Integration (CI) platforms:
 - [Red Hat Dependency Analytics Tekton Task](https://hub.tekton.dev/tekton/task/redhat-dependency-analytics)
 - [Red Hat Dependency Analytics Jenkins Plugin](https://plugins.jenkins.io/redhat-dependency-analytics/)
 
-## Know more about the Red Hat Dependency Analytics platform
+## Learn more about the Red Hat Dependency Analytics platform
 
 The goal of this project is to significantly enhance a developer's experience by providing helpful vulnerability insights for their applications.