Integrity SCM ProviderforMaven Cletus D’Souza and Ahmad Fatah Table of Contents TOC \o "1-3" \h \z \u Overview PAGEREF _Toc311708913 \h 3Installation Preparations PAGEREF _Toc311708914 \h 4Prerequisites PAGEREF _Toc311708915 \h 4Step 1: Installing Maven PAGEREF _Toc311708916 \h 4Maven SCM Goals Execution Examples PAGEREF _Toc311708917 \h 5scm:update PAGEREF _Toc311708918 \h 5scm:edit PAGEREF _Toc311708919 \h 7scm:checkout PAGEREF _Toc311708920 \h 8scm:status PAGEREF _Toc311708921 \h 9scm:checkin PAGEREF _Toc311708922 \h 10scm:add PAGEREF _Toc311708923 \h 12scm:unedit PAGEREF _Toc311708924 \h 15scm:tag PAGEREF _Toc311708925 \h 18scm:changelog PAGEREF _Toc311708926 \h 19scm:list PAGEREF _Toc311708927 \h 20scm:branch PAGEREF _Toc311708928 \h 21Integrity SCM Provider POM Configuration PAGEREF _Toc311708929 \h 22Section 1: Metadata PAGEREF _Toc311708930 \h 22Section 2: Connection to SCM Provider (Integrity) PAGEREF _Toc311708931 \h 22Section 3: Build information PAGEREF _Toc311708932 \h 23Troubleshooting PAGEREF _Toc311708933 \h 24References PAGEREF _Toc311708934 \h 25OverviewThe Integrity Configuration Management (CM) Provider for Maven provides the following capabilities that Maven expects of an SCM plug-in. Below are the definitions of the mvn commands (Goals) available to through the Maven SCM Plugin as well the specific Integrity commands that will run the accomplish these goals with specific examples.scm:branch – branch the project. Integrity Commands: Performs a si createdevpath based on the current checkpoint, if a build configuration is specified. Otherwise, a new checkpoint is created off the normal/variant configuration and a development path is created off the newly created checkpoint.scm:add – command to add file. Integrity Commands: Performs a si add for all non-members found.scm:edit – command for staring edit on the working copy.Integrity Commands: Executes si makewritable to make working files writeable in the sandbox.scm:unedit – command to stop editing the working copy. Integrity Commands: Executes si revert to undo and local modifications in the sandbox.scm:export – take a fresh copy of the project and put it all files except the project.pj files somewhere else.This command uses the default export directory for the export.Integrity command: Executes a recursive si projectco for all the files in the projectscm:changelog –command to show the source code revisions.Integrity Commands: Executes si rlog with a start and end date for the revision filterscm:list – command to display the list of all files in the project.Integrity Commands: Executes a si viewproject and displays the results.scm:checkin –command for committing changes.Integrity Commands: Executes si ci for all the changes from your sandbox.Additionally, si drop for all the missing files from your sandboxscm:checkout – command for getting the source code. This command uses the default checkout directory.Integrity Commands: Upon first check out: si createsandbox. All subsequent actions: si resync scm:status – command for showing the scm status of the working copy.Integrity Commands: Executes si viewsandbox and si viewnonmembers to provide a list of new and updated files in the sandbox.scm:update – command for updating the working copy with the latest changes.Integrity Commands: Executes a si resync on the sandboxscm:diff – command showing the difference between the working copy and the remote one. Integrity Commands: Executes si diff recursively in the sandboxscm:tag – command for tagging a certain revision.Integrity Commands: Executes si checkpoint and only labels the project, not individual members.Installation PreparationsPlease ensure that all prompts are turned off under the connection bullets within the Integrity Client Preferences Prompts Note Turn off prompts only if you don’t specify your user/password@host:port in the pom.xml for the <scm>/<connection>PrerequisitesA. Integrity Client SP6 or higher (build 4.10.0.9049).B. Maven 3.0.2+C. JAVA JDK 6.0 (Java 1.6)D. API Connections enabled on the Integrity Server.Step 1: Installing MavenThe latest and greatest version of Maven can be downloaded from the Apache website. To install, simply unzip to a directory such as C:\Maven. Place the path to the Maven bin directory in your PATH Environment Variable. For example, add the following at the end of the PATH: C:\maven\apache-maven-3.0.3\bin.Maven SCM Goals Execution ExamplesThe examples below assume you’ve followed the above setup instructions. Also, the examples make the following assumptions:An Integrity project called /JavaApps/project.pj already exists. Local Maven project folder is called C:\Maven Int\IntegritySCMTestscm:updateAssuming there is an Integrity SCM Project called JavaApps that contains the following:After running scm:update, we now have a sandbox in the desired directory:The new sandbox in Integrity scm:editnow we want to edit the working files, so we run scm:edit:scm:checkoutThis command creates a target/checkin directory within the current sandbox directory. Notice, there is no target directory:Now we run the scm:checkout command, notice it created the target/checkout directory:scm:statusNow, let’s look at the status of the working files, are they writeable? Are there more non-members?Only the changed files have been listed here, specifically the new file “Java Docs.txt”. We will run this same command later.scm:checkinNow, lets checkin our changes. I’ve made changes to HQServers.txt, commands.txt. Prior to checkin the sandbox looks like this:Running the scm:checkin command:Change Package Note:If change packages are mandatory for your project you will also need to specify a -Dmaven.scm.integrity.cpid=<cpid> on the command lineNotice we have to pass in a -Dmessage parameter with the checkin as revision description is mandatory on the Integrity side. The member history on HQServers.txt (revision 1.3) shows our Message as revision description:scm:addLets add all non-members including Java Docs.txtChange Pacakge Note:If change packages are mandatory for your project you will also need to specify a -Dmaven.scm.integrity.cpid=<cpid> on the command lineNow, the sandbox looks like this:Lets resynchronize (and get rid of all the deltas) by running scm:update:The sandbox view after running the scm:update goal:scm:uneditJava Docs.txt has been edited (checked out and modified, but not checked in) by using the scm:edit command. Edit of the Java Docs.txt file will put us at revision 1.2 if we check in. We have a delta in the sandbox, but what if we don’t want to check in the change and go back to revision 1.1 in our sandbox? Running scm:unedit removes the delta (and the changes in our sandbox).This removes the previous delta in our sandbox: It is important to point out that scm:unedit removes your local changes. Typically, a user has a file checked out and is working on it and before he/she can check it in, another user has checked in a change. What if you’d like to grab that change and make changes on against that?Scenario: I’ve checked out a file, am modifying it and I see another user has checked in the same file Now, I want to remove my changes and pull down that users change. Here is where I would use scm:unedit to remove my changes.scm:tagAfter setting up the appropriate tag in the pom.xml (as outlined in the section below), the appropriate username and date timestamp label on the checkpoint has been created for 1.5. Notice, checkpoint 1.4 where the Groovy tag was not defined contains “null_null_date”.Running the scm:tag goal:scm:changelogThis command runs the “si rlog” command which shows the source code revisions. Start and end date parameters must be passed in as shown below:scm:listThis command uses the si viewproject command, within the context of your sandbox, to list the members that reside within the project. scm:branchBranching the codebase (creating a development path) is required for many reasons. This command runs a si checkpoint command and requires a checkpoint name in the form of the -Dbranch parameter.Here is what happens on the Integrity side:Integrity SCM Provider POM ConfigurationThere is a sample POM.xml file used for developing this integration which the screenshots below reference. There are three main sections to this, each with their own screenshot.Section 1: MetadataIn this section we are defining the metadata to describe this Maven project. Notice the <artifactId> matches our Integrity project name. Although, the artifact ID can be any name, it is generally good practice to name this the same as your Integrity project name:Section 2: Connection to SCM Provider (Integrity)It is important to define both <connection> and <developerConnection> strings as the former is for read-only operations and the latter for update operations. The connection string contains three tokens, two of which are mandatory.scm:<provider>. This mandatory component defines the scm provider we are connecting to, i.e. Integrity.<username>/<password>@<host>:port. This token is optional as this plugin will borrow from the users Integrity Client User Preferences if not defined. If this token is defined; however, the @<host> is mandatory.#/<IntegrityProjectConfigurationPath>. This final mandatory token tells the plugin which Integrity project we are working with. Some sample connection strings are:Includes username and password: scm:integrity|afatah/a@alm2009:7001|#/JavaApps Relays on preferences for user/password and only references hostname: scm:integrity|@alm2009|#/javaapps Relays on preferences for user/password and only references hostname:port:scm:integrity|@alm2009:7001|#/javaappsRelays on preferences for user/password only:scm:integrity|#/JavaApps Section 3: Build informationIn this section we answer the question: “what are we trying to build”? For simplicity sake, the above example only includes one <plugin> tag, but there can be more than one. Obviously, it is required to have the maven-scm-plugin which tells maven that we’re using version 1.5 of the Maven SCM Plugin when we execute a scm:<goal>.The <configuration> tag contains a set of pre-defined properties values for the Maven SCM Plug-in (and hence the SCM Provider). We’ve defined the value for <tag> that enables the use of Groovy scripting. We are defining this here to avoid having to set command line properties at goal execution. The above <tag> defines username and a date format. Recall the scm:tag goal example above: the POM.xml file for checkpoint 1.4 did not contain the above <tag>; whereas, for 1.6 the <tag> was defined. The link in the references section goes to the maven scm plugin site. The goals outlined contain both “optional” and “required” parameters. Within <configuration> required <tag>’s should be defined and optional parameters should be defined at goal execution. For example, when running the goal scm:tag, the username and date parameters should be defined in the POM.xml file but the checkpoint description should be passed in with a -Dmessage parameter at execution. Reasoning: required tags are static (username, date) but the specific checkpoint description will be dynamic every time scm:tag is run.The Maven SCM plug-in has three dependencies listed, because the first one tells the Maven SCM plug-in what scm:<provider> to execute. The second dependency is related to our Integrity SCM Provider, i.e. the MKS JAVA API, and the third dependency is related to the interpretation of groovy script passed to the scm:tag goal for the checkpoint label. TroubleshootingSometimes mvn commands do not execute as expected due to errors. These errors are usually truncated or reduced in size. There is a ‘-X’ switch or option that can be ran with the command to enable full debug logging.For example, if the command “mvn scm:status” is not running correct, running the same command with the debug option will show debugging information “mvn -X scm:status”.ReferencesMaven SCM Plugin – this is maven scm plugin webpage that shows all the goals available for SCM Provider plugins.