Uploaded image for project: 'Minimal Marketable Features'
  1. Minimal Marketable Features
  2. MMF-1244

Warning issued during analysis and processing should be accessible from the UI

    Details

      Description

      Why

      Project analyses raise warnings at various levels:

      • During the actual analysis by scanners
      • During the processing of the reports by Compute Engine

      Some examples:

      • During the actual analysis by scanners
        • We detected that the repo is retrieved with a shallow clone, so we log a warning that the blame info for files A, B and C will be missing and therefore will have impacts on the creation date of issues or the assignees.
        • We detected that Node.js environment is missing so the analysis of CSS files was skipped.
      • During the processing of the reports by Compute Engine
        • When a PR is processed, if some configuration is missing or wrong (like a token), the decoration won't happen and the user won't understand why

      Most of the time, those warnings must be read by users to understand what needs to be done to fix a sub-optimal situation. However, as explained, users will miss those messages almost 100% of the time:

      • During the actual analysis by scanners: those messages can be seen in the logs with the WARN word - but are usually missed since most people don't look at the logs unless there is a failure (in which case they search for ERROR messages)
      • During the processing of the reports by Compute Engine: those messages can be seen in the CE logs with the WARN word - but those logs are simply not accessible to the end user

      What

      As a user who has ("Browse") access to a project, I expect:

      • to easily discover that the analysis of my project raised some warnings
      • to be able to get the details of those warnings

      Where do I expect this information to be available?

      • On the project home page:
        • I expect to see only the count of warnings, that I can click on to get the details
      • Whatever way the details are displayed, I expect to be able to read:
        • as many messages as required (i.e. if there are 10 warnings, I want to easily read them)
        • messages that are user-friendly - and so that can be potentially quite long
        • messages that are meaningful and help me fix the warnings
      • The count and the details of the warnings:
        • Relate only to the current branch/PR I'm looking at
        • Are only the warnings raised during the last analysis of the current branch/PR I'm looking at
      • In the "Background Tasks" page, I would expect to see these warnings attached to the analyses
        • For instance, a "Warnings" item in the same dropdown as "Scanner Context" - on each last analysis of branch and PR
      • Even if nothing comes to mind in terms of CE warning that might be raised for them, the solution should also work

      Warnings that should be implemented during this MMF

      Because we must not generate noise and want to give meaningful information to the user, we can't rely on the current logs provided by the analyzers, the scanners or compute engine. We prefer to go with a "white-list" approach, using a dedicated new API to push warnings to the user.

      Server side

      Inconsistent highlighting data detected on the some file(s) (X in total). [TODO wording on probable cause]
         ° [path to file 1]
         ° [path to file 2]
         ° ...
      
      • only 5 files are listed
      Pull request decoration did not happen because the token is missing. Please set it in the project settings
      
      • VSTS only
      • raised when processing the report of PR and there is no token at project level
      Pull request decoration failed because the token specified in the settings does not have sufficient rights. Please check the permissions of this token.
      
      • VSTS only
      • raised when processing the report of PR and a call to VSTS fails during PR decoration fails with a permission error
      • PR decoration runs asynchronously
      Pull request decoration did not happen. Please install SonarCloud Github application on the repositories organization/user.
      
      • same warning for BBC
      • raised when processing a PR but project is not linked, nor App is installed nor there is a token at project or global level
      • note: we specifically do not advertise for using a token as we want to remote support for it soon

      Scanner side

      Shallow clone detected during the analysis. Some files will miss SCM information. This will affect features like auto-assignment of issues. Please configure your build to disable shallow clone
      
      Some coverage tests are not taken into account during analysis of project [todo: improve wording]
      
      SCM provider autodetection failed. No SCM provider claims to support this project. Please use sonar.scm.provider to define SCM of your project.
      
      Missing blame information for X file(s). [TODO wording about consequences] Please cheek the analysis logs.
      
      Invalid character detected in X file(s). [TODO wording about consequences] Please check the analysis logs.
      
      [X] file(s) outside of module basedir was(were) ignored. Please check the analysis logs
      

      Language Plugin side

      CSS files not analysed because Node.js environment is missing when analyzing the source code
      

      SonarCss issues are tracked on GitHub, see here.

      Bytecode of dependencies was not provided for analysis of source files, you might end up with less precise results. Bytecode can be provided using "sonar.java.libraries property"
      

      Note on PR decoration

      PR decoration is triggered during report processing but *does not occur inside the task's thread* (because we don't want the task's processing time to be impacted if ALM is slow to respond). Still, it makes sense some warnings related to PR decoration are added from the PR decoration thread.

      This implies:

      • a given task may have no warning initially but then later some are added by PR decoration. Should the UI refresh policy be updated to take this into account?
      • warning can be added to DB storage from more than one source and likely concurrently (therefore, keeping an ordered list of warnings could be challenging)

      Note on linking to embedded documentation

      Being able to add link(s) to the embedded documentation in warnings would have many benefits:

      1. provides the opportunity of a longer but formatted help for users, about probables causes, fixes, ...
      2. allows writing shorter warnings
      3. when improving the doc, all warnings benefit from it, new and existing ones
      4. will allow to build a knowledge base in, eg., a page called "troubleshooting analysis and report processing"

      out of scope

      We excluded from this MMF the following points:

      • warnings that could be raised when refreshing Applications/Portoflios and when doing project import and export
      • Mark warning message as read or unread
      • Highlight the new warnings compared to ones that existed before
      • linking to embedded doc (as the idea came in late into the sprint's specification phase)

      How

      UX

      Warnings are made available through a warning banner in the header, next to the analysis date and time.

      Clicking on the link opens the details in a popup.

      The popup is also available in the Background Tasks page under the cogwheel icon as "Show warnings".

      DB storage

      Warnings are associated to a task and are stored in a specific table.
      Indexed by task UUID, it contains one row per warning.

      Benefits:

      • no need for LOB, 4000 chars per warning should be more than enough
      • counting number of warning is easy and cheap
      • concurrently added warning is not a problem
      • in case concurrent PR decoration wants to add a warning to DB before task is finalized, no problem

      Challenge of storing warnings order:

      • no specific order column: order of insertion is not guaranteed to be the order of read by SGDBs => NO
      • use autogenerated id => pitfall when it comes to DB migrations => NO
      • number column => requires a select prior to each insert to be (almost) concurrent safe => NOT GREAT
      • use of timestamp => nice, but requires all warnings sources to provide a timestamp (ie. the scanner and the CE task) => could be messed up by clock desynchronisation between scanner and server => minor issue with in fact low impact => YES, will use standard created_at column

      WebServices

      • api/ce/component
        • add field warningCount
      • api/ce/activity
        • for each task, add field warningCount
      • api/ce/task
        • add permission to call this WS with only browse on the task's component
          • required to be able to call it from the project's page (accessible with Browse)
          • avoids having to create a new specific WS to return the warnings of a given task from the project's page
        • add field warningCount
        • add array warnings, populated only if warnings is one of the values passed in parameter additionalFields

      APIs

      The feature will be implemented as a set of complementary new and updated APIs.

      Compute Engine side

      The ability for a task to raise warnings is a feature of the Compute Engine, therefor any task can use it:

      • a new internal API is added to allow any step and component inside a Task container to create warnings
      • the existing PostProjectAnalysisTask public API is extended to be able to create warnings
      • both APIs will hide the persistence complexity
        • warnings will be persisted as there are added to those APIs so that they are available even if task later fails
        • this allows this API to be used even from the PR decoration thread

      An existing Step will extended or a new one will be created to read the scanner warnings from the report and associate them to the task.

      SCM API

      The SCM API is extended to allow SCM plugins to create warnings. Those warnings will be automatically timestamped and later added to the report.

      Plugin API

      Same for the plugin API.

        Attachments

        1. Warnings_01.png
          Warnings_01.png
          226 kB
        2. Warnings_02.png
          Warnings_02.png
          191 kB
        3. Warnings_03.png
          Warnings_03.png
          145 kB

          Issue Links

            Activity

              People

              • Assignee:
                fabrice.bellingard Fabrice Bellingard
                Reporter:
                sebastien.lesaint Sebastien Lesaint
              • Votes:
                4 Vote for this issue
                Watchers:
                9 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: