This article provides guidance on using the Maven TFS SCM Provider with the Maven Release Plugin (maven-release-plugin). It is intended that this plug-in will be contributed to the Maven project, but until that time it will be available from the Teamprise Labs site along with guidance on usage.
Before using the guidance, the following pre-requisites are required:
Before using the SCM provider for a Maven project, the pom.xml file must be configured with a valid SCM URL that utilises the TFS SCM provider. The TFS SCM Url is given using the following syntax:
<scm>
<connection>
scm:tfs:[<domain>\<user>;<password>@]<tfsUrl>:[<workspace>]:<serverPath>
</connection>
<developerConnection>
scm:tfs:[<domain>\<user>;<password>@]<tfsUrl>:[<workspace>]:<serverPath>
</developerConnection>
</scm>
For example, a typical configuration might look like:
<scm>
<connection>
scm:tfs:DOMAIN\username;password@http://tfsserver:8080:mvnServerWorkspace:$/TeamProject/path/to/project
</connection>
<developerConnection>
scm:tfs:http://tfsserver:8080::$/TeamProject/path/to/project
</developerConnection>
</scm>
Where the main connection has a specific username, password and TFS workspace provided to talk to TFS and the developer connection ommits those values so that the current working folder is used to determine the TFS workspace and the credentials taken from the current users context.
Until the TFS SCM provider is included in the Maven project, it is necessary to add a dependency on the relevant plug-ins so that they are aware of the SCM provider when a TFS operation is executed. To do this add the following dependencies:
<build>
<plugins>
...
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-scm-plugin</artifactId>
<dependencies>
<dependency>
<groupId>org.apache.maven.scm</groupId>
<artifactId>maven-scm-provider-tfs</artifactId>
<version>1.0.0</version>
</dependency>
</dependencies>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-release-plugin</artifactId>
<dependencies>
<dependency>
<groupId>org.apache.maven.scm</groupId>
<artifactId>maven-scm-provider-tfs</artifactId>
<version>1.0.0</version>
</dependency>
</dependencies>
</plugin>
...
</plugins>
</build>
The TFS SCM Provider can be invoked from the command-line using the SCM plugin. Please refer to the SCM plugin usage details to issue SCM commands to a TFS server. The complete set of goals is listed here. Note that the Maven SCM commands are heavily influenced by the language used by Subversion. For example:
mvn scm:checkout -DcheckoutDirectory=<dir>
gets the latest version of the server path to the specified directory. If the serverPath is already mapped to a different directory, the TFS SCM provider automatically updates the mapping before proceeding to get the latest version to the specified directory To edit a file with TFS, you must first issue a TFS check-out command, which in Maven terminology is an edit command.
To perform a check-in of a file(set):
mvn scm:checkin -DworkingDirectory=<dir> -Dincludes=*.xml
checks in the set of files that match the comma-separated includes file pattern
The Maven Release Plugin is intended to help in releasing a project, without repetitive, manual work. In order to use the Maven release plugin, we must first have specified a dependancy on maven-scm-provider-tfs (see above).
The release plug-in is geared towards version control systems (such as SubVersion) that have local files read/write. The TFS version control protocol requires that the files are read-only locally until a check-out (edit) is performed. To get the release plug-in to perform a TFS check-out before editing the pom.xml file use the -DuseEditMode=true flag.
When performing a release, there are two major steps - prepare and perform.
prepare: checks for uncommitted changes, prepares the release by tagging the code with an appropriate version name and commits all changes of versions. E.g.
mvn release:prepare -DuseEditMode=true
perform: checkout the prepared release, and run the predefined maven goals to release the project Eg.
mvn release:perform -DuseEditMode=true -DconnectionUrl=<scmUrl> -DworkingDirectory=c:\temp\release\mvn
Note that when doing a release:perform, the release plug-in wants to download a fresh copy of the source to a location on disk. By default this is inside the target directory for the project - however it is a limitation of TFS that a server path can only be mapped to a single local path in a TFS workspace. Also a different workspace cannot map to a child local path of another workspace. Therefore, when we execute a release:perform we have to force this to occur in a different local path and in a different workspace.
We should be able to pass both a working directory and an SCM url on the release:perform command line, however there is a bug in the current released versions of Maven that prevent us from doing this (http://jira.codehaus.org/browse/MRELEASE-382). Therefore we must add the following workingFolder configuration to our POM (in our example we are setting the release working directory to occur in c:\temp\release\mvn).
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-release-plugin</artifactId>
...
<configuration>
<workingDirectory>c:\temp\release\mvn</workingDirectory>
</configuration>
</plugin>
Assuming the working folder is being passed through the pom.xml as described above, an example command to perform a release once this file has been edited would be:
mvn release:perform -DconnectionUrl=scm:tfs:http://tfsserver:8080:mvnReleaseWorkspace:$/TeamProject/main/source/project
-DuseEditMode=true