Synchronizing status changes and comments across projects

You can run the cross-project synchronization tool, kwxsync, to copy issue status changes and comments to other projects sharing the same source code. This means that developers need to cite detected issues only once.

Prerequisites

If an access control method has been configured (Basic, LDAP or NIS), the user performing cross-project synchronization (or 'xsync') needs to do the following:
  • Each server needs a user with the 'Perform cross-project synchronization' permission. By default, Project root admins and project admins are given this permission. This is a project root level permission (therefore, it is not assignable on the project level).
  • For every server to which kwxsync connects and that has an access control method enabled, an entry, which specifes a 'machine:port:user:token' (For example, jsmith2.klocwork.com;8080;jsmith;e46db6b8582a) combination, is required in the 'ltoken' file on the machine that is running kwxsync. To generate an entry in this file for a given machine or machines, the user must run kwauth for each relevant server and log in with the account which contains the proper permission; kwauth then stores and updates a token in the user's home directory.
  • The user that ultimately connects is the user whose role memberships, under certain conditions, will be tested. It is recommended that you configure a special role which contains the 'Perform cross-project synchronization' permission only.

When you attempt to perform the synchronization, kwxsync proceeds only if the user has the proper permissions to do so on each of the specified machines. If the user does not have the proper permissions, all machines on which it did not pass and the user name with which it did not pass will be logged, and the kwxsync process will exit.

If connecting to a machine that does not have an access control method in place and an entry does not exist for the target machine in the ltoken file, the name of the user that is logged in on the machine that is running kwxsync will be used. Each project referenced in the kwxsync command-line has either an explicit URL (http://jsmith:8080/project_A) or an implicit URL (project_B). If a project has an implicit URL, its server and port are assumed to be the same server and port specified by the value of the --url parameter.

See Synchronizing status changes and comments across projects for how-to information.

Here's an example of how kwxsync can be useful in the software development process.

  1. A software module exists in the main trunk of your source code repository. We'll call the Klocwork project for this source code module ProjectMain.
  2. You create a branch of this source code module, so that bugs can be fixed. Developers continue their feature work on the main trunk.
  3. You create a Klocwork project for the branch, as shown above. We'll call this project ProjectBranch.
  4. You run a Klocwork build analysis on ProjectBranch.
  5. Developers investigate reported issues found in ProjectBranch. They change the status for some issues, and add comments.
  6. You run a Klocwork build analysis on ProjectMain. At this point, none of the citing work that developers performed on ProjectBranch appears in the ProjectMain build analysis.

How kwxsync solves this problem

You can run kwxsync to copy developers' changes from the branch to the main trunk. For example:

kwxsync ProjectBranch ProjectMain

kwxsync applies the most recent status-changes and comments from ProjectBranch to ProjectMain, and from ProjectMain to ProjectBranch. All of the updates are merged, so that identical issues in the two projects have an identical history.

Since you can specify multiple projects for kwxsync, and you can run kwxsync continuously, you can ensure that all projects sharing source code are always up to date. To run kwxsync continuously, call it in a loop (for example, a looping batch file). You can improve performance when running kwxsync continuously by specifying the --last-sync option.

See kwxsync for usage, options and examples.

Detailed example of cross-project synchronization behavior

To understand exactly how issue statuses and comments are synchronized, consider the following example.

We have two projects, ProjectMain and ProjectBranch. They each contain an identical code issue, which we'll refer to as IssueMain and IssueBranch. Developers cited these issues as follows:

Time IssueMain IssueBranch
@time1 Fix -- "This is a problem"  
@time2   Ignore -- "This can be ignored"
@time3 Not a problem -- "This is not a real problem"  

Running the command kwxsync ProjectMain ProjectBranch merges the entire history of IssueMain and IssueBranch, preserving the citing time. As a result, the new citing history of IssueMain and IssueBranch will be as follows (we've truncated the information for brevity):

Time IssueMain IssueBranch
@time1 Fix -- "This is a problem" From ProjectMain: Fix -- "This is a problem"
@time2 From ProjectBranch: Ignore -- "This can be ignored" Ignore -- "This can be ignored"
@time3 Not a problem -- "This is not a real problem" From ProjectMain: Not a problem -- "This is not a real problem"

Performing a "dry run" synchronization

If you'd like to preview the changes before they're made, you can perform a "dry run". With the --dry option, kwxsync won't actually synchronize the issue status updates and comments; instead, it will just output a list of these changes to the console.

If you'd like to output the potential changes to an HTML report, use the --output option as well as the --dry option. kwxsync will create an HTML report for each project, with the project name as part of the output file name. For example, if you run this command:

kwxsync --dry --output report.htm Project1 Project2 Project3

kwxsync will create three files: report_Project1.htm, report_Project2.htm and report_Project3.htm.

Generating a synchronization report

To generate a synchronization report, just add the --report <file> option to your kwxsync command line. You can create a synchronization report during synchronization, or as part of a "dry run".

Example: Creating a report during synchronization

kwxsync --report report.txt Project1 Project2 Project3

Example: Creating a report during a "dry run"

kwxsync --dry --report report.txt Project1 Project2 Project3

Format of the synchronization report

The synchronization report has the following format:

<unique_issue_id>;<project_name>;<project_issue_id>

kwxsync assigns a unique ID to each detected issue. This detected issue may exist in multiple projects.

Each detected issue also has a project-specific ID; this is the ID that you see in Klocwork Static Code Analysis.

Tip: Grouping the synchronization report by unique issue ID provides a count of unique issues detected across all projects.

Sample synchronization report

This sample shows a synchronization report for three projects named zlib, zlib_br, and zlib_trend.
14;zlib;1
4;zlib;2
8;zlib;3
5;zlib;5
6;zlib;6
7;zlib;4
1;zlib_trend;7
10;zlib_trend;1
11;zlib_trend;9
4;zlib_trend;2
8;zlib_trend;3
5;zlib_trend;5
6;zlib_trend;6
7;zlib_trend;4
2;zlib_trend;8
1;zlib_br;7
11;zlib_br;9
4;zlib_br;2
8;zlib_br;3
5;zlib_br;5
6;zlib_br;6
7;zlib_br;4
2;zlib_br;8

You can group this data by unique issue ID to get a list of unique issues detected across all projects:

Image:kwxsync-sync-report-table.png