README in rscm-0.2.1.1404 vs README in rscm-0.3.0

- old
+ new

@@ -1,25 +1,35 @@ -= RSCM - Ruby Source Control Management (0.2.0) += RSCM - Ruby Source Control Management (0.3.0) -RSCM is to SCM what DBI/JDBC/ODBC are to databases - an SCM-independent API for accessing a wide variety of SCMs. The features are roughly: +RSCM is to SCM what DBI/JDBC/ODBC are to databases - an SCM-independent API for accessing different SCMs. The features are roughly: * Check out a working copy (with possibility to specify branch/date/label) * Get changesets (changesets are emulated for non-transactional SCMs like CVS and StarTeam) * Get diffs * Add and commit files * Manipluate triggers +Although RSCM's main focus is operations on a working copy of an SCM repository, the API also allows some level of interaction +with the SCM repository itself, like creating new repositories. + == Download RSCM is available as a RubyGem, and can be installed like this: gem install rscm +(You may need administer access to do this on a POSIX system). If you want the latest and greatest, you can get the sources, which live alongside DamageControl's sources: - http://damagecontrol.codehaus.org/Installing +* See the DamageControl Developer Guide at http://hieraki.lavalamp.ca/ +== Team +* Aslak Hellesoy - All +* Steven Baker - Monotone +* Jon Tirsen - CVS, Subversion +* Yogi Kulkarni - Perforce + == Supported SCMs * CVS - http://www.cvshome.org (stable) * Perforce - http://www.perforce.com (not thoroughly tested) * StarTeam - http://www.borland.com/starteam (not thoroughly tested) @@ -28,11 +38,11 @@ In progress: * ClearCase -http://www-306.ibm.com/software/awdtools/clearcase (half way there) * Darcs - http://www.abridgegame.org/darcs (very incomplete) * Monotone - http://www.venge.net/monotone (half way there) - + Planned: Loads! All of them! How to add support for a new one is described further down in this file. == Related projects @@ -44,34 +54,35 @@ Here is an example of how to use RSCM to get a list of changesets from a CVS repository: require 'rscm' scm = RSCM::Subversion.new("svn://some.server/some/path/trunk", "trunk") + scm.checkout_dir = "/my/working/copy" - scm.checkout("mycheckout") - changesets = scm.changesets("mycheckout", Time.utc(2004, 11, 10, 12, 34, 22)) - changesets.each do |changeset| - puts changeset + scm.checkout + revisions = scm.revisions(Time.utc(2004, 11, 10, 12, 34, 22)) + revisions.each do |revision| + puts revision # or do something more funky with it end === Using visitors -Although ChangeSets and ChangeSet support external iteration (as in the example above), the preferred way -to operate on them is to let a ChangeSets object +accept+ a visitor. A visitor +Although the Revisions and Revision classes support external iteration +(with +each+ as in the example above), they also support +visitor traversal via their +accept+ methods. A visitor must respond to the following methods: - def visit_changesets(changesets); end - def visit_changeset(changeset); end - def visit_change(change); end + def visit_revisions(revisions); end + def visit_revision(revision); end + def visit_file(revision_file); end === Getting diffs -RSCM allows you to get diffs for changesets. This is done in the following way: +RSCM allows you to get diffs for changesets. See the DamageControl sources for more detailed +examples (DamageControl persists diffs to disk and presents them as colourised diffs in its +user interface). -See the DamageControl sources for more detailed examples (DamageControl persists diffs to disk -and presents them as colourised diffs in its user interface). - == Future plans === Cross-SCM synchronisation RSCM could be used as a tool to migrate files from one SCM to another (of a different type) @@ -82,11 +93,11 @@ the central SCM and one that you set up on your local machine. = Implementing support for a new SCM We'd be happy to receive contributions for more SCMs. You can always -file a JIRA issue and hope for someone to implement it for you, or +file a JIRA issue (http://jira.codehaus.org/browse/DC) and hope for someone to implement it for you, or you can do it yourself. The rest of this file should get you started. N.B. IF YOU START IMPLEMENTING A NEW RSCM PLUGIN, PLEASE SUBMIT YOUR CODE TO JIRA AT AN EARLY STAGE (BEFORE IT'S COMPLETE). THIS WAY IT'S EASIER FOR EXISTING DEVELOPERS TO PROVIDE TIPS AND HELP UNDERWAY. @@ -103,11 +114,11 @@ By including GenericSCMTests your test will automatically include the acceptance test suite for RSCM. By doing this you'll actually follow a TDD approach for your new Mooky class - except that the tests are already written for you! -IMPORTANT NOTE: If your SCM doesn't provide an easy way to create new local repositories +IMPORTANT NOTE: If your SCM doesn't provide an easy way to create new local repositories (such as with StarTeam) you're probably better off writing the tests from scratch and not include GenericSCMTests. Instead, just make sure you have an SCM repository set up somewhere and write tests to work against that repository. This way you won't be able to pass the generic acceptance test suite, and other people (like the RSCM dev team) will probably not be able to run the tests for it. -But it's better than nothing. We'll happily accept @@ -160,12 +171,12 @@ Java classes for ChangeSets that allow easy interaction between Ruby and Java over YAML. You can reuse these classes for other Java based SCMs (if there are any, I don't know). == Web interface (DamageControl only) -DamageControl automatically detects new SCM classes in RSCM and generates a default web interface. - +DamageControl automatically detects new SCM classes in RSCM and generates a default web interface. + = Building RSCM This section is for developers who are new to ruby development and do not already know how to build and install Ruby gems. You need to install rubygems from http://rubyforge.org/projects/rubygems Afterwards you need to install rake and rails @@ -176,8 +187,8 @@ rake gem This will create a gem for RSCM. To install this gem, you have to change to the pgk directory and type - sudo gem install pkg/rscm-0.1.0.gem + sudo gem install pkg/rscm-0.3.0.gem -Now you can use RSCM in other Ruby apps. +Now you can use RSCM in other Ruby apps with a simple require 'rscm'.