-
Notifications
You must be signed in to change notification settings - Fork 36
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* add dynamic reports enhancement Signed-off-by: Pranav Gaikwad <[email protected]> * add details on some of the stories Signed-off-by: Pranav Gaikwad <[email protected]> * 🐛 update Signed-off-by: Pranav Gaikwad <[email protected]> --------- Signed-off-by: Pranav Gaikwad <[email protected]>
- Loading branch information
1 parent
d20d007
commit d4b6200
Showing
1 changed file
with
156 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,156 @@ | ||
| --- | ||
| title: Dynamic Reporting | ||
| authors: | ||
| - "@pranavgaikwad" | ||
| reviewers: | ||
| - "@rromannissen" | ||
| - "@jwmatthews" | ||
| - "@jortel" | ||
| approvers: | ||
| - "@rromannissen" | ||
| - "@jwmatthews" | ||
| - "@jortel" | ||
| creation-date: 2023-03-15 | ||
| last-updated: 2023-03-21 | ||
| status: implementable | ||
| --- | ||
|
|
||
| # Dynamic Reports | ||
|
|
||
| The results of source code and binary analysis are vital to assessment of applications. They enable users to define and plan appropriate migration strategies in the later stages of the Konveyor methodology. So far, Konveyor relies on Windup output to present the results of these analyses. It is largely static and isn't stored in Konveyor. It is limiting in that Konveyor cannot aggregate the analysis results for multiple applications in the inventory. | ||
|
|
||
| In this enhancement, we present Dynamic Reports. Dynamic Reports use the analysis data created by the new LSP analyzers. They can be generated on-demand for one or more applications from the most recent analysis data available in Konveyor. They enable users to see analysis information of multiple applications in one place to get a high level of migration issues across their portfolio. At the same time, they allow the users to drill down into specifics of each issue. | ||
|
|
||
| ## Motivation | ||
|
|
||
| With the upcoming integration of new LSP analyzers in Konveyor, the data generated by analyzers becomes a first class entity in Konveyor. We talked about this in our previous enhancement on [Reporting Format](./TODO: Link here). It opens up lots of possibilities for Konveyor in terms of what it can do with the data. We want to leverage that and improve reporting capabilities of Konveyor. Dynamic reports are simply reports that give users much more control on what information is displayed via filters, visualizations, etc. They bring important information across all applications in the inventory in one place and make it easier for users to query that information. | ||
|
|
||
| ### Goals | ||
|
|
||
| We only intend to define requirements and scope for dynamic reports. | ||
|
|
||
| ### Non-Goals | ||
|
|
||
| We do not intend to discuss technical details in this enhancement. More enhancements will follow for technical details on implementation. | ||
|
|
||
| ## Proposal | ||
|
|
||
| The two main components of the dynamic reports we are proposing are Issues, and Dependencies. An issue indicates a problem in the source code that needs to be solved for successful modernization / migration. | ||
|
|
||
| ### Issues | ||
|
|
||
| An issue is analogous to a _Violation_ created by the analyzer. They are created when analyzer finds a match for a Rule. | ||
|
|
||
| Issues have following properties: | ||
|
|
||
| * Description: A text description in markdown format | ||
| * Rule ID: Rule for which the issue was created | ||
| * Category: Helps define severity of issue | ||
| * Effort: A numeric value denoting efforts needed to fix the issue | ||
| * Hyperlinks: External links that provide additional information pertaining to the issue | ||
| * Incidents: Occurrences of the issue across the source code. Each incident will have a file URI and a message that helps show information about that particular incident. | ||
|
|
||
| ### Dependencies | ||
|
|
||
| Analyzers output dependencies for an application with each dependency having following properties: | ||
|
|
||
| * Name: Name of the dependency. | ||
| * Version: Version of the dependency. | ||
| * SHA: Checksum of the dependency. | ||
| * Indirect: Whether the dependency is indirect. | ||
| * Type: Type of the dependency. | ||
|
|
||
| ### User Stories | ||
|
|
||
| We define two scopes for the reports: | ||
|
|
||
| * Portfolio scope: This is the part of report which is in the context of all or a selected subset of applications in the inventory. | ||
|
|
||
| * Application scope: This is the part of report which is in the context of one specific application. | ||
|
|
||
| #### Portfolio scope | ||
|
|
||
| ##### Dependencies | ||
|
|
||
| * As a user, I want to be able to see a list dependencies across a selected subset applications in the inventory. (See [application selection](#selection-of-applications)) | ||
|
|
||
| * As a user, I want to be able to filter dependencies by whether the dependency is a direct or an indirect dependency. | ||
|
|
||
| * As a user, I want to be able to see a list of name of the dependencies shared by two or more applications in the inventory. (See [shared dependencies](#shared-dependencies)) | ||
|
|
||
| ##### Issues | ||
|
|
||
| * As a user, I want to be able to see a list of all issues generated by the analyzer for a selected subset of applications in the inventory. (See [application selection](#selection-of-applications)) | ||
|
|
||
| * As a user, I want to be able to see issues that belong to one or more applications. (See [grouping](#grouping-of-issues)) | ||
|
|
||
| * As a user, I want to be able to filter issues by their category, effort and name of the source / target technologies. (See [technology filters](#technology-filters)) | ||
|
|
||
| * As a user, I want to be able to use filter by one or more criterias at a time to further narrow down my search of issues. (See [Filters on multiple columns](#filters-on-multiple-columns)) | ||
|
|
||
| #### Application scope | ||
|
|
||
| ##### Dependencies | ||
|
|
||
| * As a user, I want to be able to see a list of dependencies for a specific application. | ||
|
|
||
| * As a user, I want to be able to see a tree of dependencies so that I can distinguish between a direct and an indirect dependency. | ||
|
|
||
| * As a user, I want to be able to filter Java dependencies by package groups. (See [java package groups](#filter-dependencies-by-package-groups)) | ||
|
|
||
| ##### Issues | ||
|
|
||
| * As a user, I want to be able to see a list of all issues for an application. | ||
|
|
||
| * As a user, I want to be able to filter issues by their category and effort. | ||
|
|
||
| * As a user, I want to be able to see number of issues that belong to each category with their associated story points. | ||
|
|
||
| * As a user, I want to be able that belong to "mandatory" category broken down by their effort with associated story points for each level of effort. | ||
|
|
||
| ### Implementation Details/Notes/Constraints | ||
|
|
||
| #### Selection of applications | ||
|
|
||
| Since there could be thousands of applications in the inventory, displaying all issues / dependencies for all applications in the inventory might not be ideal for user experience. In this enhancement, we are proposing that the users select a subset of applications via a separate filter for which they want to see the list of issues or dependencies. They can also select all applications, but we want that to be the choice of the user. | ||
|
|
||
| #### Grouping of issues | ||
|
|
||
| At the portfolio level, there's value in displaying impact of an issue or dependency across their portfolio. For the report, it translates into an ability to show distinct issues grouped by applications. Looking at an issue or a dependency, the user needs to be able to see how many applications have the same issue or use the same dependency. | ||
|
|
||
| #### Shared Dependencies | ||
|
|
||
| When finding dependencies between two or more applications, it is implied that the dependencies will only be matched using their names. Note that dependencies have more fields than names such as versions, SHAs etc. | ||
|
|
||
| #### Technology filters | ||
|
|
||
| Technologies are modelled as name of the technology along with a range of versions of the technologies, both being string values. In this enhancement, the proposed filter is based only on the name of the technology, and does not filter on version of the technology. | ||
|
|
||
| #### Filters on multiple columns | ||
|
|
||
| One or more columns can be combined together to form complex searches. When filtering by multiple columns, logical AND between different types of columns is implied. Within the same type of columns, however, selecting multiple values implies a logical OR. For instance, when I select "mandatory" for the category column, and "java" and "golang" for target technology, it is implied that a list of issues with "mandatory" category AND with target technologies "java" OR "golang" will be returned. | ||
|
|
||
| #### Filter dependencies by Package Groups | ||
|
|
||
| From analyzers perspective, Name field of a dependency would have fully qualified name for the dependency. It makes the most sense to have a generic "Name" field to accomodate all different kinds of dependencies out there for different technologies. As a result, implementing a filter based on Java package group names implies a full text search within names of dependencies. | ||
|
|
||
| ### Descoped to future | ||
|
|
||
| ##### Statistics | ||
|
|
||
| There are two types of statistics proposed - first, statistics generated from the most recent analysis available for applications and second, statistics generated from the history of all analyses that were executed so far. | ||
| ###### Based on most recent analysis data | ||
|
|
||
| * As a user, I want to see total number of issues that belong to the "mandatory" category across a selected subset of applications in the inventory. | ||
|
|
||
| * As a user, I want to be able to see all categories of issues with their associated story points across a selected subset of applications in the inventory. | ||
|
|
||
| _See [current statistics](#current-statistics)_ | ||
|
|
||
| ###### Based on historical data | ||
|
|
||
| * As a user, I want to be able to see trend of story points of issues belonging to "mandatory" category generated from the history of all analyses. | ||
|
|
||
| * As a user, I want to be able to see trend of number of issues in each category from the history of all analyses. | ||
|
|
||
| _See [historical data](#historical-data)_ |