Teamscale Docs

Appearance

Creating a Guideline ​

You can annotate Teamscale findings with rules from your internal company guidelines. This is achieved by creating custom guidelines within Teamscale.

Overview ​

The process of creating a guideline in Teamscale involves the following steps:

  1. Identify Relevant Rules: Determine the specific rules and standards that are most important for your project's quality goals.
  2. Locate Corresponding Teamscale Checks: Utilize Teamscale's user interface to find the pre-existing checks that correspond to the rules you identified in the previous step. These checks will automatically analyze your codebase for adherence to your defined rules.
  3. Prepare the Guideline Files: Follow the instructions detailed below to create the necessary files for your guideline.
  4. Import and Use the Guideline Files:
    • On-Premise Installation:
      Create a folder named guidelines within the config directory of Teamscale. For each individual guideline you are creating, establish a separate subdirectory within the guidelines folder. Copy the guideline files you prepared in step 3 into the respective subdirectory. This ensures that the guideline is recognized by Teamscale and analysis of your projects will annotate findings that correspond to guideline violations.
    • Cloud Installation:
      For cloud-based Teamscale installations, please reach out to the Teamscale support team at support@teamscale.com for assistance with uploading and configuring your custom guideline.
  5. Restart Teamscale after creating or modifying a guideline.

In case of an error creating the guideline in Teamscale, you can find the error log entry in the log-file named logs/teamscale.log.

Prepare the Guideline Files ​

For each guideline you have to prepare the following three files:

  • guideline.txt
  • guideline-rules.tsv
  • guideline-rules-to-checks.tsv

All files must be UFT-8 encoded.

Information about Guideline: guideline.txt ​

The guideline.txt file contains general information about your guideline. It has a simple key: value format. Example:

ID: my-company-guideline
Readable Name: My Company Guideline
Language: JAVA, CS, CPP
Upstream URL:
Archive URL:
Author/Organization: CQSE GmbH
Release Date: 2025
Description: This is a sample programming guideline for Java, C# and C++.
Further Info URL: https://example.com/my-company-guideline

If the guideline applies to multiple programming languages, specify them as a comma-separated list using the following abbreviations:

  • ABAP
  • ADA
  • CS (C#)
  • C
  • CPP (C++)
  • COBOL
  • DART
  • DELPHI
  • ESQL (Extended SQL)
  • FORTRAN
  • GO
  • GOSU
  • GROOVY
  • SQLScript
  • IEC61131 (IEC 61131-3 ST)
  • JAVA
  • JAVASCRIPT (includes TypeScript)
  • KOTLIN
  • MATLAB
  • OBJECTIVE_C
  • OPEN_CL
  • OSCRIPT
  • PHP
  • PLSQL
  • PYTHON
  • SIMULINK
  • SWIFT
  • TSQL (Transact-SQL)
  • VB (Visual Basic)
  • XML
  • Xtend

Information about Guideline Rules: guideline-rules.tsv ​

The guidline-rules.tsv file defines all individual rules of your guideline in TSV (Tab-Separated Values) format. TSV is a text-based format used to store data in a tabular structure. Each line represents a row of data, and columns within each row are separated by tab characters. Each rule includes the following fields:

  • ID in Guidelines: A unique ID of the rule (mandatory)
  • Readable Name: A human-readable name shown in Teamscale (mandatory)
  • Category: Grouping for large guidelines with many rules (optional)
  • Machine-checkable: Indicates whether the rule can be automatically checked (optional)
  • Comments: Comments will not be shown in Teamscale (optional)
  • Upstream URL: URL with further information (optional)

You can download here an example file and adapt it to your needs:

guideline-rules.tsv

Mappings Guideline Rules To Teamscale Checks: guideline-rules-to-checks.tsv ​

The guideline-rules-to-checks.tsv file links the rules of your guideline to Teamscale checks. With this mapping, Teamscale can annotate findings with references to your guideline rules. As with guideline-rules.tsv, this files uses the TSV format. Each mapping includes the following fields:

  • Check ID: ID of the Teamscale check (mandatory; see below)
  • Guideline Rule ID: The ID of the rule as specified in guideline-rules.tsv (mandatory)
  • Comment: Comments will not be shown in Teamscale. (optional)

A rule can be mapped to multiple Teamscale checks by having multiple rows with the same Guideline Rule ID. You can download here an example file and adapt it to your needs:

guideline-rules-to-checks.tsv

Supported Checks

Currently it is not possible to map rules to checks that depend on external uploads such as Findbugs.

Where can I find the check ID?

The check ID is not the same as the check title displayed in Teamscale. You can find the check ID by hovering over the check title in the Check Explorer. For example, in the screenshot below, the check ID for "Avoid leaving deprecated entities" is cqse-deprecated-annotation.

screenshot_check_id.png