Semmle 1.20
Skip to end of metadata
Go to start of metadata

This topic describes how to make the snapshot source code revision number available in the snapshot and dashboard databases so that it can be displayed in Project Insight or Enterprise Insight. Team Insight always includes details of the source code revision number.

-

Project configuration files generated by the bootstrap tool for projects that check out code from Git, Subversion or Mercury repositories automatically include a build command to include the source revision number.

Overview

Each snapshot has metadata associated with it, including the name and date of the snapshot. You can define additional metadata for the snapshot, for example, the revisionKey key which defines a revision number for the source code. If the revision number for a snapshot is stored as the revisionKey then it is automatically displayed in the snapshot selector shown in Project Insight and you can update your Enterprise Insight configuration to display the revision number. Team Insight automatically determines the revision number during analysis and makes the information available in the Team Insight views.

While you could define the revision for each snapshot manually, for most projects it is better to define an additional build command in the project file to return the revision number of the source code and add it as metadata to the snapshot (the bootstrap tool does this automatically for check outs from Git, Subversion and Mercury repositories). You can update the configuration files for existing projects so that all new snapshots include the source revision number as follows:

  1. Determine a method for calculating the source code revision number for the snapshots of the project - this will vary according to the source code management system used and your precise checkout/build environment. 
  2. Edit the project file and define an additional build step to set the revisionKey for each new snapshot built by the buildSnapshot command.

-

If you use a simple check out from Git, Subversion or Mercury then you may find it easiest to use bootstrap to create a new project configuration file and simply copy the appropriate build command into your existing project file.

-

Determining a method for getting the revision number

The best method for getting the revision number for a snapshot will depend on which source code management system you use and also the build environment. You must identify a command that can be run in the snapshot source directory to determine a source code revision number. Here are some possible commands for commonly used source code management systems:

  • Git—you might use git log -n1 --format=%h
  • Mercurial—you might use hg log -l1 --template {node|short}
  • Perforce—you might use  p4 changes -m1 @YOURCLIENTNAME | cut -d' ' -f2
  • Subversion—you might use svnversion -n

This can then be used to define an additional build step (see below).

The enhanced variable expansion introduced in Semmle 1.9.3 allows you to call the editSnapshot command directly, including the call to the source code management system as a variable to the command. This provides a platform-independent build step to set the revision number.

Adding a step to the build process to automatically include a revision number

You can update the project file to include a new build step to set the value of revisionKey. For example, you might insert the following build step immediately after the final checkout step:

Example build command for a Git project on any platform (Semmle 1.9.3 onward)
<build>odasa editSnapshot --concurrent --set-metadata revisionKey $(=git --git-dir=${src}/.git log -n1 --format=%h) ${snapshot}</build>

When this additional build step runs it determines and sets the revision for the snapshot source code and stores this information in the  ODASA_SNAPSHOT/external/data/snapshotMetadata.csv file, ready for further processing. When this command is complete, the other build steps are executed as normal.

Any snapshots added to the project after these changes will include the revision number.

Displaying the revision number

When a snapshot revision number is available, it is automatically displayed in the Snapshot selector displayed in the top right corner of most Project Insight pages:

In this example you can see that one snapshot has been created since the build step to include the revision number was added to the project configuration file. If you want to display the revision number in Enterprise Insight then you will need to update the database configuration queries to process the revision number and then update the Business Intelligence dashboards to display the new information.

Updating existing snapshots to include a revision number

You can update the metadata for existing snapshots without rebuilding the source code using the editSnapshot command. For example, you might run:

odasa editSnapshot --project projects\avro --set-metadata revisionKey "123456" revision-2014-April-27--05-03-00

to set the revisionKey for the snapshot revision-2014-April-27--05-03-00 in the avro project to 123456.

If you want to update the dashboard to display the new revision data in Project Insight without adding a new snapshot, then you should:

  1. Use updateExternalData to update the snapshot database to include the new metadata, for example:
    odasa updateExternalData --project projects\avro revision-2014-April-27--05-03-00
  2. Delete the deployed subdirectory of the main dashboard directory (in this example, dashboards/avro/deployed).
  3. Run the buildDashboard command. The deletion of the deployed subdirectory forces the regeneration of the dashboard and ensures that the new revisionKey is included in the updated dashboard. 
  4. When the dashboard build is complete, use the add-dashboard script to add the dashboard to the web server and open Project Insight.