Interpolating messages

[jmle]

Currently, for rules with custom variables like the following

- category: mandatory
  customVariables:
  - name: renamed
    nameOfCaptureGroup: renamed
    pattern: javax.(?P<renamed>(activation|annotation|batch|decorator|ejb|el|enterprise|faces|inject|interceptor|jms|json|jws|mail|persistence|resource|security|servlet|transaction|validation|websocket|ws|xml))?.*
  description: javax.{renamed} has been replaced by jakarta.{renamed}
  effort: 1
  labels:
  - konveyor.io/target=jakarta-ee9+
  - ...
  message: 'Replace the `javax.{{renamed}}` import statement with `jakarta.{{renamed}}`
  ruleID: javax-to-jakarta-import-00001
  when:
    as: javaClass
    java.referenced:
      location: IMPORT
      pattern: javax.(activation|annotation|batch|decorator|ejb|el|enterprise|faces|inject|interceptor|jms|json|jws|mail|persistence|resource|security|servlet|transaction|validation|websocket|ws|xml)*

we interpolate the message field only in the incidents shown in the snippets. This makes sense, since we bundle all the different incidents, with the different matches (and therefore potential interpolable variables) in a single issue.

As a consequence, there is no single way of interpolating the message field for it to be shown when the issue is opened (see screenshot, right below rule id), since there are multiple possibilities.

A possible solution could be to interpolate the general message for the issue with all the different matches found, or'ing them:

javax.(jms|mail|ejb) has been replaced by jakarta.(jms|mail|ejb)

Another possibility is to have an additional, modified message field for showing in the description, which wouldn't have any
template for interpolation, although this would require extensive modification of the rulesets.

What do you think?

[fabianvf]

I think for the short-term option 2 is probably ok. I do like the ORing approach though, we'd probably have to limit it to a reasonable number of occurrences (10 maybe) and then just append a |... at the end to leave the message readable. I think that's a good solution for when we have to display a message for an issue, though I think for the most part we should try to display description (if provided) in those cases if we can.

[rromannissen]

The OR approach looks quite elegant to me, and I like Fabian's suggestion to limit the number of occurrences, although 10 seems to be a bit too much, I imagine 3 or 4 would be more than enough to get the gist of it. Having to modify the message for all rules doesn't seem to be practical to me. My only concern with the OR approach would be to determine how that might affect the shim when converting already existing rules.

[shawn-hurley]

I worry about how, if we make the message dynamic in this way, we roll up the issues into a wider view across applications into a migration wave for instance. I think that has been the primary driver in my mind to make the message not dynamic

[rromannissen]

I agree with @shawn-hurley, it might get messy when aggregating issues across multiple applications in the UI. Then, I feel like the second option that @jmle proposed could work:

Another possibility is to have an additional, modified message field for showing in the description, which wouldn't have any
template for interpolation, although this would require extensive modification of the rulesets.

I imagine that field would take precedence over the regular message field in the UI, so it would be displayed at issue detail level with the regular interpolated messages being displayed at incident level. WDYT?

[shawn-hurley]

Based on this convo, I am proposing the fix is:

1. Create a new field in RuleMeta called Title. This will then be used if available.
2. We manually fix our rules (maybe creating a patch file that can be applied after converting)? so that they look nice.

Do folks agree?

[jmle]

Sounds good. I would try to find other name for the field though, IMO what we call description should be the title, and what we call message should be the description. Maybe message could be the new field, although this would imply changing all the rules :(

[shawn-hurley]

Description I think right now makes sense; it should describe what the rule is for and why.
Message I think that this also make sense to me, it is a specific message that an incident is attempting to convey.

The new field needs to be a "short name to describe what the rule is for quickly," at least in my opinion, and that is why I think that Title makes sense.

[rromannissen]

I think I agree with @jmle on this one. The way I see it, fields should be arranged in the following way:

• Title: Provides a short summary of what the issue is all about. Should be displayed on the Issue column from the Issues view and as a headline on the right panel from the expandable row.
• Description: Generic explanation of the issue at hand with no interpolation. It should be displayed on the the right panel from the expandable row from the table in the Issues view.
• Message: Detailed explanation of an incident of a given issue that might include interpolation. Should be displayed on the incident detail for a given file.

I hope this makes sense!

[shawn-hurley]

I think that is what I was attempting to advocate for as well @rromannissen. Sorry if I did a poor job.

I also agree with where and when things should be displayed.