What the ClearCase UCM Plugin can do?

Monitor changes in your ClearCase UCM VOBs by polling for new baselines on a given stream, in a given component with a given promotion level.

Does not require ClearCase to be installed on the master

No config spec to setup! The plugin establish a snapshot view in the jobs workspace, which is self-contained an 100% compliant with all the plugin that allows you to brows the workspace from the web.

Either PROMOTE or REJECT the baseline given the build result, success, unstable or failure.

Sets the description of the individual job, listing the baseline built, the result and the new promotion level.

Can recommend the baseline if it is promoted.

Can tag the baseline with the result of each individual job, so that history and statistics are persisted, not only in Jenkins, but also in ClearCase itself.

Supports concurrent builds - without finding the same baseline twice even when previously started jobs are still in progress (currently only supported with one iterator per slave).

ClearCase MultiSite is fully supported:

Slaves and masters can be in different ClearCase regions and even at completely different Sites

Polling for Posted Deliveries is supported

Supports pre-tested commits by monitoring either child streams (development streams within the project) or sibling streams (integration streams in other projects) and automatically deliver into the integration stream and finally complete or cancel the deliver based on the build result.

For the impatient

Prerequisites:

ClearCase UCM Plugin assumes that a default view storage location is available in your region (it probably is, and if it's not you can easily create one using 'cleartool mkstgloc').

If you want to use the 'tag' function in the post-build section, you have to set up a hyperlink type named 'tag' in your VOB (details below).

ClearCase Client must be installed on slaves that shall execute the build (ClearCase is not required on the master). Due to JENKINS-25342 we require ClearCase to be installed on the master.

We assume that all your computers have unique names in your network.

Configuration

Main configuration screen for Clearcase UCM Plugin.

A short description of the configuration options are listed below

Basic settings: Stream and Component Promotion level

Essentially the plugin is looking for new baselines on a specific stream belonging to a specify stream. On top op that you have to qualify which baselines are of interest in this context by applying a Promotion Level. Only baselines found that matches all three parameters will kick off the build.

When the build ends, the promotion level will either be stepped one level up (if successful) or rejected.

If you have a configuration where you use more than one component in your foundation, you may wonder why we only left room for specifying one single component - please take the time require to read the blog post on "[The rationale behind the ClearCase UCM plugin for Jenkins CI|http://www.praqma.com/stories/ccucm]"

Basic settings: Load Modules

The plugin will automatically create a snapshot view in a folder named 'view' in the root of the job's workspace. Snapshot views can - as opposed to dynamic views - be located anywhere, which we exploit to place itinside the job's workspace. Dynamic Views can only reside on the location where your mvfs is located and that isnot inside the workspace.

A lot of plugins have browsing features, that allows you to see the code in the browser, high-lighted to make a point in the context (warnings, violations, code coverage...) In order to guarantee compliancy with these type of plugins we only support snapshot views.

In general build performance is also much better in snapshot views that are hosted by the clients native file system - once they are loaded.

We us a separate view per job, per client, which allows us to reuse views in a context the only changes very little between builds. Thus you will find that once you have loaded the view the first time, the successive updates will be very fast, since deltas are guaranteed to be small.

You have a small handle of control of what load-rules are applied to the snapshot views; Either you load all the components or only the modifiable ones.

Basic settings: Recommend Baseline

If the checkbox Recommend baseline is set, a successful build will recommend the baseline that was used.

Basic settings: Make tag

When the checkbox Make tag is checked, the plugin will persist the build status in ClearCase, by writing a small summary of the status as a to-text object at the end of a hyperlink of type tag attached to the baseline.

NOTE:The if you want to use this feature then the hltype:tag should be created first

Basic settings: Set description

When Set description is checked, the build description in the left margin of the job page is updated with the details of the build. Super crisp feature! Check i out!

Advanced: Unstable jobs

Some of the features in the post build section to the plugin such as the pre-tested delivery features available in poll child and poll sibling mode, and the 'Recommend baseline' checkbox ways to make boolean decisions; complete or cancel? Recommend or not? But the outcome of a Jenkins job really has three possible states; Succes, unstable and failure. You will have to decide if the unstable state should due treated as success or failure.

Polling Modes

ClearCase UCM Plugin supports three types of polling modes.

Self polling

Child polling

Sibling polling

Rebase polling

Subscribe polling

Self Mode

Self mode enables you to find baselines on the stream itself given a promotion level.

If the build is successful, the plugin can recommend the baseline and it will promote it to the next level.

If the build has failed, the plugin will demote the baseline to rejected.

About the streams created in this mode, see the advanced section.

Note that this is the only mode creating auxiliary streams.

Child and Sibling Mode

This mode enables you to find baselines on related streams of the target stream. This is either development streams of the target stream(child mode) or other integration streams having this stream as default target(sibling mode).

If the build is successful, the baseline is delivered to the target stream and you can choose to create a baseline on it. The baseline of the other stream is promoted to the next level.

The plugin can recommend the new baseline on the target stream.

If the build has failed, the plugin will demote the baseline of the other stream to rejected and no deliver activity is made, and thus no baseline is created on the target stream.

Rebase Mode

This mode. based on the selected stream will compare the set of foundation baselines for a given stream, and check to see if there are newer baselines on any of the component streams. If so, the plugin will trigger

and the target stream will be rebased to the selected baselines.

Subscribe Mode

Special polling mode that subscribes to data about compatibility of a certain set of baselines. Currently there is only one plugin that provides information this mode. The Config Rotator plugin.

Create baseline and baseline template

The option Create baseline and Name template enables you to create a baseline on the target stream. The name template is made up of free text with optional keywords, expanding to run time variables:

stream - The given UCM Stream

project - The UCM Project

component - The given UCM Component

date - The date in yyyymmdd

time - The time in hhmm

number - The current Jenkins build number

user - The user created the Baseline

env - Get an environment variable. [env=var]

file - Retrieve the content of a file residing in the workspace. [file=SOME_FILE]. [file=myfile] will expand to path/to/workspace/myfile and the content of the file is used. (Only a single, short line of text is supported, and it goes without saying that the string must conform to the restrictions to characters supported in baseline names)

Keywords are enclosed in square brackets([]). For example [project][date][time] will result in the baseline myproject_20110915_1128.

The plugin's baseline naming feature is meant to run on the UCM Project's default baseline naming template just containing "basename".

Notice that this option has no meaning for self polling or if the Create baseline option is not checked.

Latest Baseline

Like the Git and Mercurial plugins, ClearCase UCM Plugin also supports polling for the latest baseline. This means, when polling, a build is scheduled only if there's a new baseline on the stream.

To be able to poll for the latest baseline, the special promotion level ANY and self polling must must be selected in the setup.

Advanced SCM setup

Build Project The plugin creates a separate read/only development stream and snapshot view for every self polling job on every slave that executes the job. The stream and view is created the first time the job is executed on the slave and then reused by successive job executions. If you just go with the defaults settings the streams will be created as child streams to the integration stream in the project holding the baseline that is being built, but despite the reuse of these Jenkins related streams, there is still a tendency that you end up with a lot of extra streams on behalf of the plugin. You can remove them if you want to, but the jobs will then just create them again next time they run. In order to keep your ClearCase Project Explorer tidy we've made the option to place them in an auxiliary project made specifically for this purpose (in general, development streams must be in the same UCM project as the baselines you rebase them against , but read/only streams are considered special cases and they can live safely be in a separate project). Here's the deal: If you make a project in ClearCase named 'hudson' or 'jenkins', the plugin will put the auxiliary streams there. If you prefer another name for this specialCCUCM -related project, you can specify it in the Build project box in the 'Advanced' section

Tagging To be able to tag your baselines, you need to create a ClearCase hyperlink type named "tag" in each UCM project vob, that will be holdding the baselines, you can do that with the following command:

Do not remove the view private files By default the view private files are removed from the workspace every time a build is executed. This can be avoided by unchecking "Remove view private files".

Trimming the change log This is only useful in poll-self mode, and will filter off changes from contributing activities.

Build a specific baseline with a parameterized build

Parameterizing your build with a string called baseline will let you build a specific named baseline. This baseline name is the value of the parameter. This feature will let you have one job, that does the polling on SCM and then has a post-build step orchestrated by the ﻿Parameterized Trigger Plugin which builds the same baseline. The downstream job, should have the same settings for stream and component - and if you set the promotion level to ANY, the downstream job will not change the built baseline's promotion level.

Build variables

The ClearCase UCM plugin introduces several build variables:

CC_BASELINE the baseline being build

CC_VIEWTAG the view tag

CC_VIEWPATH the path of the view(the same as %WORKSPACE%\view)

Limitations

The plugin supports concurrent builds.

Currently you can only have one build at the time per node. Set # of executors to 1 in your node configuration if you want to use concurrent builds with ClearCase UCM Plugin.

Only one deliver activity per stream, which means child and sibling modes cannot be executed concurrently.

Run Jenkins service under a valid ClearCase account

Jenkins needs to be authenticated by ClearCase, so it's important that you run the Jenkins service under an account that has the sufficient access to ClearCase. The ClearCase UCM Plugin fully supports that a slave can be in a different ClearCase region or even at a completely different ClearCase MultiSite than the master.If you utilize this feature, it's required that the slave is running Jenkins under an account which has the sufficient credential on the remote site

ClearCase unavailable

The plugin will state in the console output, when ClearCase is not available. This concerns both when it is not installed and when there are no licenses available. If a build has been scheduled, its description is set with the cause.

If you don't get any scheduled builds, check your poll log. This is where to find information, if ClearCase is unavailable.

MultiSite - tag your nodes

If you have slaves in different MultiSites than the master, you can tie the jobs that monitors stream that has mastership on foreign sites to slaves that belongs to those sites. A simple strategy for this is that you add a tag to all you slaves telling which MultiSite they belong to and then you tie the jobs to those labeled slaves.

MultiSite - polling for posted deliveries

The plugin supports polling for posted deliveries in a MultiSite environment. This feature must be turned on at the Jenkins global settings for the plugin, and only has effect in child polling mode. Normally in this mode, the plugin will harvest all baselines made in child streams. If the stream is at a different site, this is not possible. In this setup, the plugin can work in two different modes:

Standalone mode: The process is a bit different from normal: on top of making the baseline, the developer must issue a Deliver Baseline command. A special "Posted deliver" object is then created, and the mastership of the development stream is transferred to the integration stream site. The plugin will detect the posted delivery, and resume and complete (or cancel) the delivery. As a result of this, the mastership of the stream will be transferred back to the origin. Notice: The ClearCase posted delivery process does not transfer the mastership of the baseline - for that reason the promotion level of the baseline cannot be changed, but is left as INITIAL. Tags can also not be updated.

ClearCase trigger mode: We have developed a ClearCase trigger to set and reset the mastership of the baselines - if this trigger is installed on both the development and integration site, the plugin will behave exactly the same way as in a single site setup: the developer just creates baselines, and everything else will happen automatically. The trigger can be found here: http://wiki.praqma.net/acc/comp/triggers/acc_deliver_baseline. For more information, or help to set this up, please contact Praqma.

Special debugging parameters

Setup logging with plugin versions prior to 1.2.0

For debugging purposes a job can be parametrized to output debug log information to a file. The parameters are string parameters.

ccucm_logall - Enable logging(the value part is empty)

ccucm_loglevel - The severity of the log level

DEBUG - Huge amount of output

VERBOSE

INFO

WARNING

ERROR

FATAL - Only the worst

Note that these names are case sensitive!

The logs can be found in the jobs build folder under each specific build folder where the debug has been enabled. This means you have to browse into the master Jenkins server.

The SCM log is named ccucmSCM.log and the post-build log is named ccucmNOTIFIER.log.