Mailing-List: contact scm-commits-help@maven.apache.org; run by ezmlm
Precedence: bulk
Reply-To: scm-dev@maven.apache.org
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
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 -0000
To: scm-commits@maven.apache.org
From: mperham@apache.org
Message-Id: <20061202041854.749151A9846@eris.apache.org>

Author: mperham
Date: Fri Dec  1 20:18:50 2006
New Revision: 481503

URL: http://svn.apache.org/viewvc?view=rev&rev=481503
Log:
Add site documentation describing the Perforce provider and how it works

Added:
    maven/scm/trunk/maven-scm-providers/maven-scm-provider-perforce/src/site/
    maven/scm/trunk/maven-scm-providers/maven-scm-provider-perforce/src/site/apt/
    maven/scm/trunk/maven-scm-providers/maven-scm-provider-perforce/src/site/apt/index.apt

Added: maven/scm/trunk/maven-scm-providers/maven-scm-provider-perforce/src/site/apt/index.apt
URL: http://svn.apache.org/viewvc/maven/scm/trunk/maven-scm-providers/maven-scm-provider-perforce/src/site/apt/index.apt?view=auto&rev=481503
==============================================================================
--- maven/scm/trunk/maven-scm-providers/maven-scm-provider-perforce/src/site/apt/index.apt (added)
+++ 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)
+
+Details
+
+ 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.
+
+ * <<<maven.scm.perforce.clientspec.name>>> - 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.
+
+Troubleshooting
+
+ * 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.