Managing Check Descriptions

During the analysis of projects in Teamscale, findings are created from checks configured in Analysis profiles. The explanation and rationale of the findings are described in markdown files of checks. There may be (customer-specific) contexts that require deviations of check descriptions.

Overriding Checks Descriptions

Since Teamscale version 6.4, it is possible to adjust check descriptions without re-deployment.

To adjust finding descriptions, start by identifying the config folder in the Teamscale installation or working directory. Therein create the folder finding-descriptions. For some given check, create a markdown file with the desired descriptions text, according to the path {ANALYSIS_TOOL}\{CHECK_ID}.md. The {ANALYSIS_TOOL} corresponds to the analysis tool to which the check belongs. The {CHECK_ID} as in the previous section identifies the markdown file name. For example, to override descriptions for the "Interface comment completeness" and Model Advisor's "Check signal line labels" checks, the paths will be:

1. Teamscale\Interface comment completeness.md
2. MODEL_ADVISOR\Check signal line labels.md

Note that analysis tool names and check ids can be found in the Analysis Profile view. Afterwards, the new descriptions would be visible in the finding detail views and analysis profiles for all findings of the check, i.e. for existing findings created before the change and for new findings created afterwards. This feature works by storing these new descriptions in a cache in Teamscale. In the event that updated descriptions do not load, use the debug service api/debug/reset-findings-description-override-cache to reset the cache and then refresh the finding detail or analysis profile view.

Loading Check Descriptions without Reanalysis after Teamscale Patch Update

After some Teamscale instance has been updated to a patch version in which some checks descriptions have changed, the descriptions will not be immediately visible for respective findings created before the update. While a project re-analysis is usually required to address this, it can be a time-consuming process for projects with large histories.

To load the descriptions and have them immediately visible, create a projects-and-checks.json file in the config or custom-checks directory of the Teamscale installation or working directory. The contents of the JSON file should follow the schema below, to specify the projects as well as the checks whose descriptions need to be loaded.

  [
     {
         "projects":["public-project-id-x", "project-project-id-y"],
         "checks":[
                {"analysis-group": "AG-1", "id": "ID-1"},
                {"analysis-group": "AG-2", "id": "ID-2"},
                ...
         ]
     },
      ...
  ]

The check ids in the JSON file should be markdown file names of the checks without the ".md" extension. Check ids and analysis group names can be found in the Analysis Profile view.

To effect the changes, restart Teamscale. Note that this feature is available starting from Teamscale version 8.4.17.