maven-scm-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r481503 - in /maven/scm/trunk/maven-scm-providers/maven-scm-provider-perforce/src/site: ./ apt/ apt/index.apt
Date Sat, 02 Dec 2006 04:18:53 GMT
Author: mperham
Date: Fri Dec  1 20:18:50 2006
New Revision: 481503

Add site documentation describing the Perforce provider and how it works


Added: maven/scm/trunk/maven-scm-providers/maven-scm-provider-perforce/src/site/apt/index.apt
--- maven/scm/trunk/maven-scm-providers/maven-scm-provider-perforce/src/site/apt/index.apt
+++ maven/scm/trunk/maven-scm-providers/maven-scm-provider-perforce/src/site/apt/index.apt
Fri Dec  1 20:18:50 2006
@@ -0,0 +1,44 @@
+ --------------
+ Maven Perforce SCM provider
+ --------------
+ Mike Perham
+ --------------
+ 01 December 2006
+ --------------
+Maven Perforce SCM provider
+ The Perforce provider acts as a "driver" between Maven's generic SCM API and the Perforce
SCM system.
+Use Cases
+ The provider must handle a number of different usecases:
+ * Check out to a directory or update that source regularly as part of a build server (Continuum)
+ * Label a source tree and check out that label to a temp directory (the release plugin)
+ * Map a number of commands designed for CVS/SVN onto the (frequently) very different semantics
provided by Perforce (the scm plugin)
+ The main semantic issue faced by the provider is CVS/SVN's concept of a working copy versus
Perforce's concept of a clientspec.  CVS/SVN allow the user to checkout any repository location
to any local directory at will and tracks this by keeping metadata in a CVS/.svn directory.
 Perforce instead uses a "clientspec" to track any number of repository locations and how
they map onto the local filesystem.
+ Consider the complications required just to check out source to a directory.  The provider
cannot assume that it can modify the current or default clientspec so it needs to create a
clientspec.  But since clientspecs are persistent it needs to know if it should delete the
clientspec (the release plugin) or keep the clientspec around so it can be used to refresh
the source tree in the future (build server).
+ The provider uses a few system properties to control how it operates.
+ * <<<>>> - Allows you to override the
default name created by the provider.  By default the provider creates a clientspec with the
name "<username>-<hostname>-MavenSCM-<localpath>" to ensure uniqueness and
tracability.  If you want to use a pre-existing clientspec or conform to a corporate naming
standard, you can just pass the name here and the provider will use it instead.  This property
is most useful for scenarios where you want the clientspec to be retained, as with Continuum.
+ * <<<maven.scm.persistcheckout>>> - Controls whether the Perforce provider
will delete
+ the clientspec once the operation is done.  In the case where we just want to check out
a source tree to a temporary directory (like with the release plugin), we want this to be
false since there is no reason to keep the clientspec around.  On the other hand, when used
with Continuum, you want to remember the checkout so that repeated syncs take a minimum of
time.  The default is false.
+ * Under the covers, the provider just executes the <<<p4>>> command. 
<<<p4>>> must be in your path.
+ * Make sure <<<p4 info>>> returns your correct information.
+ * The provider does not login for you.  You must run <<<p4 login>>> before
any Maven SCM commands will work.  If you need automated SCM operations (e.g. you are using
Continuum on a build server), it is recommended that you use a special Perforce user whose
login does not time out.
+ * Ensure that your module has a valid SCM element and the depot path is correct.

View raw message