| -------------- |
| 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 |
| |
| <<<scm:accurev:[user/pass[@host[:port]]][:streamName][:?key=value&key=value...][:/project/path]>>> |
| |
| * <user/pass> See login below. |
| |
| * <@host:port> Specify the accurev server to connect to. If used all accurev commands will include a |
| <<<-H host:port>>> argument. |
| |
| * <streamName> provide a "version" for initial checkouts. Only really required for HEAD/trunk type |
| checkouts such as done by the tck tests. |
| |
| * <?prop=value> various properties |
| |
| * <accurevExe> Path to the accuRev executable |
| |
| * <tagFormat> 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.<propertyname>" |
| |
| * </project/path> 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 <<<accurev login>>> externally. For automated SCM operations (e.g. Continuum), |
| suggest using <<<accurev login -n>>> 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 <<< <server> >>> section in a settings.xml file. |
| |
| If supplied then we will login to the server with <<< accurev login <user> -A >>>. This returns an |
| authentication token to the process which is used in subsequent command invocations by passing |
| |
| <<< -A <authtoken> >>> to the accurev cli. |
| |
| * <<Warning>> this method will expose your accurev session token to anyone snooping command lines (eg via ps) |
| and will be exposed in debug output |
| |
| * <<Warning>> under Windows the user's password is passed on the command line, and will be exposed in debug output |
| |
| * <<Note>> We never logout. AccuRev returns the same session id for a user anyway, and unused sessions will expire. |
| |
| * Checkout |
| |
| * Persistent checkout (<<<isPersistCheckout() == true>>>) |
| |
| 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 <<</project/path>>> 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 <<<accurev chws -b>>>. |
| |
| If the checkout location is not an existing workspace then a new one is created with <<<accurev mkws>>> |
| |
| 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 <<<accurev pop -V -l >>> 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 <<<accurev update>>>. 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 <<<accurev chws>>> 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 <<<accurev add>>> |
| |
| * Checkin |
| |
| Keep and promote any pending files. <<< accurev promote -K >>> |
| |
| * Status |
| |
| Runs a series of <<<accurev stat>>> calls to identify various types of modifications. |
| |
| * <<<accurev stat -D>>> defunct files => "DELETED" status |
| |
| * <<<accurev stat -k>>> kept files |
| |
| * <<<accurev stat -m>>> modified files |
| |
| * <<<accurev stat -b>>> 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. |
| |
| |
| * <<<accurev stat -M>>> missing files => "MISSING" status |
| |
| * <<<accurev stat -x>>> external files => "UNKNOWN" status |
| |
| * Changelog |
| |
| List the changes promoted into a stream between times/transaction ids. |
| |
| <<<accurev hist -s stream -t T1-T2>>> |
| |
| For AccuRev > 4.7.2 also issues |
| |
| <<<diff -v stream -V stream -t T1-T2>>> |
| |
| 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 |
| |
| <<Not yet implemented>> |
| |
| Diff between versions. If only a base directory supplied in the fileset will diff the whole workspace. |
| |
| If both version specified |
| * <<< accurev diff -v <start> -V <end> >>> |
| |
| If only one version specified then comparison is against workspace filesystem |
| * <<< accurev diff -v <start|end> >>> |
| |
| If no versions specified and stream is in URL, then compare workspace to that stream |
| * <<< accurev diff -v <urlStream> >>> |
| |
| If no versions specified and no stream in URL, then compare workspace to basis stream |
| * <<< accurev diff -b >>> |
| |
| |
| * Remove |
| |
| <<<accurev defunct>>> the elements specified in the fileset, or the whole basedir |
| |
| * Blame |
| |
| <<<accurev annotate>>> 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 <<<accurev mkstream>>> 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. |
| |
