-------------- Maven SCM AccuRev provider -------------- Grant Gardner -------------- January 2009 -------------- ~~ Licensed to the Apache Software Foundation (ASF) under one ~~ or more contributor license agreements. See the NOTICE file ~~ distributed with this work for additional information ~~ regarding copyright ownership. The ASF licenses this file ~~ to you under the Apache License, Version 2.0 (the ~~ "License"); you may not use this file except in compliance ~~ with the License. You may obtain a copy of the License at ~~ ~~ http://www.apache.org/licenses/LICENSE-2.0 ~~ ~~ Unless required by applicable law or agreed to in writing, ~~ software distributed under the License is distributed on an ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY ~~ KIND, either express or implied. See the License for the ~~ specific language governing permissions and limitations ~~ under the License. ~~ NOTE: For help with the syntax of this file, see: ~~ http://maven.apache.org/doxia/references/apt-format.html The AccuRev provider implements Maven's generic SCM API for the AccuRev SCM system. Use Cases The provider must handle a number of different use cases: * Label a source tree and check out that label to a temp directory (the release plugin) * Provide a changelog between dates/revisions and checkout code to a directory (Continuum et al) * Map a number of commands designed for CVS/SVN onto the semantics provided by AccuRev (the scm plugin) Details The main semantic issue faced by the provider is CVS/SVN's concept of a working copy versus AccuRev's concept of a workspace. 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. AccuRev uses a "workspace" concept whereby it keeps track of the physical filesystem locations within the server. This necessarily creates restrictions on where projects may be checked out to, in that overlapping workspaces are not allowed. The other major constraint is the uniqueness of workspace and tag names which cannot be reused. It is up to the user to implement some namespace standards to manage this. URLS <<>> * See login below. * <@host:port> Specify the accurev server to connect to. If used all accurev commands will include a <<<-H host:port>>> argument. * provide a "version" for initial checkouts. Only really required for HEAD/trunk type checkouts such as done by the tck tests. * various properties * Path to the accuRev executable * Maps branch/tag/version names to AccuRev stream names and vice-versa. See the "tag" command below. If provided all streams are expected to conform to this naming standard. The above can also be referenced as system properties - "maven.scm.accurev." * is the relative path of your project within AccuRev. Note that AccuRev has no concept of checking out a sub-directory so checkouts always create this physical path under the working directory. NOTE: There is no specification of depot as it can be derived from the working directory or stream names. SCM Commands * Login The recommended method is to run <<>> externally. For automated SCM operations (e.g. Continuum), suggest using <<>> to create a persistent login that won't expire in the middle of your build. If you really want to embed this information in URLS and config files, read on. Username and password can either come from the URL, or from a <<< >>> section in a settings.xml file. If supplied then we will login to the server with <<< accurev login -A >>>. This returns an authentication token to the process which is used in subsequent command invocations by passing <<< -A >>> to the accurev cli. * <> this method will expose your accurev session token to anyone snooping command lines (eg via ps) and will be exposed in debug output * <> under Windows the user's password is passed on the command line, and will be exposed in debug output * <> We never logout. AccuRev returns the same session id for a user anyway, and unused sessions will expire. * Checkout * Persistent checkout (<<>>) The basic premise is to end up with a workspace rooted at the checkout directory with contents as at the specified version. Versions are of the form [basisStream/[tranid|timestamp]]. If a version is not supplied, the streamName from the url is used as the basisStream for the workspace. A non-empty checkout directory is not allowed. It will be created if it does not exist. If the checkout directory is a subdirectory of an existing workspace other than the <<>> specified in the URL then the checkout will be aborted. If a workspace exists at the checkout location then it will be reused. If necessary the basisStream of the workspace will be reparented with <<>>. If the checkout location is not an existing workspace then a new one is created with <<>> Workspace names are generated by concatenating the basis stream and the base name of the checkout directory unless the basis stream contains the base name or vice versa, in which case the longer one is used. If the generated workspace name already exists as stream name elsewhere in AccuRev then the checkout will fail. The final step is to update the workspace to the tranid/timestamp specified in the supplied version (or "highest" if not specified). Note that workspaces cannot go backwards, even when reparented or repopulated and you will get "transaction out of range" errors if you try. Since you can't update a workspace to a transaction less than one used to create it, any transaction information supplied for an initial checkout will be silently ignored. * Non persistent checkout If the persistCheckout flag is false, the provider redirects the checkout to the export command as below. * Export A populate outside of a workspace <<>> If the checkout directory exists within a subdirectory of a workspace AccuRev would normally generate an error. To work around this restriction the existing workspace is temporarily deactivated during the export. For AccuRev 4.9.x the provider supports export to a specific tranid/timestamp. * Tag Creates a snapshot <<< accurev mksnap >>> for the basis stream of the workspace specified by the working directory. A system property "maven.scm.accurev.tagFormat" can be used to specify a java.util.Formatter string used to convert from a maven scm tag name to an accurev stream name for the snapshot. Useful for the release plugin in cases where you have a certain stream naming convention enforced by an AccuRev admin trigger. * Update Equivalent to <<>>. The working directory must be in a workspace (or reftree) and that whole workspace is updated. here has been the option to populate to a specific transaction id. A version of the form basisStream/timeSpec can be supplied (tag/branch/revision). If the basis stream of this version is different to the current basis of the workspace, then a <<>> is performed. The timespec component is passed as the <<< -t >>> option to the update command. If not supplied the timespec is set to "highest". Changelog with update is supported. If no start_date for the changelog is supplied, then we start from the transaction id of the workspace before the update. The end version for the changelog is the supplied version as above (defaulting to "now"). If the start and end versions refer to the same basis stream, then a changelog is performed using the changelog command described below. If the streams are different, then a dummy changeset is synthesised to simply list the updated files. * Add Equivalent to <<>> * Checkin Keep and promote any pending files. <<< accurev promote -K >>> * Status Runs a series of <<>> calls to identify various types of modifications. * <<>> defunct files => "DELETED" status * <<>> kept files * <<>> modified files * <<>> to find state of kept and modified files in the backing stream to determine whether their Maven ScmFileStatus is "ADDED" or "MODIFIED". An unintended change in stat -b output for AccuRev 4.9.0 breaks this distinction. * <<>> missing files => "MISSING" status * <<>> external files => "UNKNOWN" status * Changelog List the changes promoted into a stream between times/transaction ids. <<>> For AccuRev > 4.7.2 also issues <<>> to synthesise a changeset representing files that have changed upstream. If the version specifies a workspace stream the history of the workspace is merged with the above hist/diff performed on the workspace's basis stream * Diff <> Diff between versions. If only a base directory supplied in the fileset will diff the whole workspace. If both version specified * <<< accurev diff -v -V >>> If only one version specified then comparison is against workspace filesystem * <<< accurev diff -v >>> If no versions specified and stream is in URL, then compare workspace to that stream * <<< accurev diff -v >>> If no versions specified and no stream in URL, then compare workspace to basis stream * <<< accurev diff -b >>> * Remove <<>> the elements specified in the fileset, or the whole basedir * Blame <<>> the specified file file must be in a workspace/reftree * Branch Not implemented. The Maven SCM branch concept possibly could be represented as some form of <<>> but not sure this really does the stream concept justice. Troubleshooting Generally to get yourself out of trouble you'll need to manipulate AccuRev externally by moving workspaces around bumping versions, reparenting or renaming streams.