README in rscm-0.4.3 vs README in rscm-0.4.4

- old
+ new

@@ -1,6 +1,6 @@ -= RSCM - Ruby Source Control Management (0.4.3) += RSCM - Ruby Source Control Management (0.4.4) RSCM is to SCM what DBI/JDBC/ODBC are to databases - an SCM-independent API for accessing different SCMs. The high level features are roughly: * Check out a working copy (with possibility to specify branch/date/label) * Get revisions (changesets) (Emulated for non-transactional SCMs like CVS, ClearCase and StarTeam) @@ -16,18 +16,16 @@ RSCM is available as a RubyGem, and can be installed like this: gem install rscm -(You may need administrator access to do this on a POSIX system). -If you want the latest and greatest, you can get the sources: +(You may need administrator access to do this on a POSIX system). You can also download prebuilt gems from +http://rubyforge.org/frs/?group_id=490 -Anonymous: - svn co svn://svn.damagecontrol.codehaus.org/damagecontrol/scm/trunk/rscm +If you want the latest and greatest, you can get the sources from subversion: -Developers: - svn co svn+ssh://developer@beaver.codehaus.org/home/projects/damagecontrol/scm/trunk/rscm + svn co svn://buildpatterns.com/svn/repos/rscm/trunk == Contributors * Aslak Hellesoy - All * Steven Baker - Monotone @@ -51,132 +49,144 @@ Loads! All of them! How to add support for a new one is described further down in this file. == Related projects -* DamageControl - http://damagecontrol.buildpatterns.com. DamageControl is a Continuous Integration system -built around RSCM and Ruby on Rails. +* DamageControl - http://dev.buildpatterns.com/trac/wiki/DamageControl (Continuous Integration system +built on top of RSCM and Ruby on Rails). == Sample usage Here is an example of how to use RSCM to get a list of revisions (aka changesets) from a subversion repository: require 'rscm' scm = RSCM::Subversion.new("svn://some.server/some/path/trunk") - scm.default_options = {:stdout => "stdout.log", :stderr => "stderr.log"} # What follows would look the same for any supported SCM revisions = scm.revisions(Time.utc(2004, 11, 10, 12, 34, 22)) # For Subversion, you can also pass a revision number (int) revisions.each do |revision| puts revision # or do something more funky with it end -=== Using visitors - -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_revisions(revisions); end - def visit_revision(revision); end - def visit_file(revision_file); end - == Future plans === Cross-SCM synchronisation - RSCM could be used as a tool to migrate files from one SCM to another (of a different type) while keeping the history. -Similar to cvs2svn or http://nautilus.homeip.net/~lele/projects/tailor/ RSCM could also be used as a continuous synchronisation service between SCMs. This can be very useful when you have to work with an SCM and you'd rather use a different one. RSCM could synchronise between the central SCM and one that you set up on your local machine. -= Implementing support for a new SCM +=== SCM browser +A rails webapp that allows browsing of a repository, using RSCM to access it. -Perhaps even with a simple +editor allowing people to modify files and commit them via the browser. -We'd be happy to receive contributions for more SCMs. You can always -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. += Implementing a new RSCM adapter -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. +If you want RSCM to support a new SCM, you must implement a subclass of RSCM::Base. +You should focus on implementing only the features that you need. For example, if +you plan to use your new RSCM adapter with DamageControl, you only need to implement +the parts of the API that are used by DamageControl. -Let's write an RSCM implementation for the imaginary SCM called Mooky. -You should be able to use the same recipe for most SCMs. +We'll see what steps are needed to make an adapter that passes the DamageControl compatibility suite +(which is part of RSCM). Let's imagine we want DamageControl to be able to work with the imaginary SCM +called Mooky. The rest of this section explains how to get started. You're going to need a preexisting +repository with some existing contents, basic knowledge of the SCM's command line tools and some Ruby +programming skills. -== Writing the API +== Create the test class and the implementation class -Start by writing a test: +Start by writing a test that includes the compatibility test suite you're interested in: - test/rscm/mooky/mooky_test.rb + test/rscm/scm/mooky_test.rb -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! +With the following content: -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 -contributions that don't use the generic tests, although it would be best if they did. + require 'rscm/test_helper' -OK, back to mooky. As you will see in a minute, the generic test suite will be of great -help when developing the Mooky class. The tests will attempt to check in some sample files -and call various methods on the mooky object to verify that it behaves correctly according -to the RSCM API. (The sample files consist of some java sources, but you don't need Java installed. -They're just files). + module RSCM + class MookyTest < Test::Unit::TestCase + include Compatibility::DamageControlMinimal + end + end -Let's implement the Mooky class. Take a look at. +Now create the implementation class: lib/rscm/scm/mooky.rb -Try running Mooky's test: +With the following content: + require 'rscm/base' + + module RSCM + class Cvs < Base + end + end + +Now that we have set up the basics, we can run the tests: + rake test TEST=test/rscm/scm/mooky_test.rb - -Whoops - we got some failures! It failed because our checkout method returned -nothing (nil). Let'see if we can get the a little further by implementing this -method. -The Mooky SCM happens to have a command line utility to perform a checkout. -From the command line a checkout with mooky would be done like this: +It will fail - there is still some setup to do: - cd somewhere - mooky checkout --repo mooky://some/where/else +== Create testdata directory +You must create a new directory under test/rscm/compatibility to contain testdata. Give it a name representative +of the scm type and the contents of the scm. For example, if the existing mooky repository we're going to test +against contains source code for a chess engine, we could call the directory test/rscm/compatibility/mooky_chess. -Running this command will print the following to standard out: +Also add an entry in test/rscm/compatibility/config.yml mapping your test class to the testdata directory. - checkout build.xml - checkout project.xml - checkout src/java/com/thoughtworks/damagecontrolled/Thingy.java - checkout src/test/com/thoughtworks/damagecontrolled/ThingyTestCase.java - -What we need to do is to execute these commands from Ruby. We also need to -parse the output from the mooky command to determine the files that were checked out, -so that we can return an array with the file names of the checked out files (the method -should also yield each file name as the execution proceeds). +The DamageControl compatibility suite expects to find three YAML files in this directory, scm.yml, revisions.yml +and files_0.yml. -Once your checkout command works okay, the test will get you a little further. Just keep -on going until all tests pass. +=== Create scm.yml +This file should contain a YAML representation of the SCM instance used for testing. The test suite will load it to create an instance of your class. You're free to use whatever properties you want in your SCM implementation, and the YAML file should +contain the necessary values to connect to the preexisting repository. -NOTE: If the SCM doesn't have a command line utility (unlikely) or a 3rd party Ruby API, but instead -provides libraries (perhaps in C), then you should consider writing a Ruby C extension -instead. +=== Create revisions.yml +This file should contain a RSCM::Revisions object with two RSCM::Revision objects. You can start off by making a copy of one of the +existing revisions.yml files, but you should hand-edit this file to represent two revisions in the existing repository. -If the SCM has a Java interface, you can take the same approach as for StarTeam. There are -Java classes for Revisions 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). +You cannot choose any revision though. There are some constraints that need to be followed: +* There must be exactly two RSCM::Revision objects +* The two RSCM::Revision objects must represent to adjacent revisions from the repository +* Each of the RSCM::Revision objects must contain at least two RSCM::RevisionFile objects +* The second RSCM::Revision object must contain at least one RSCM::RevisionFile with "ADDED" state -== Web interface (DamageControl only) +Given these constraints you should spend some time locating two revisions that follow these constraints. +This would be a good time to familiarize yourself with the SCM's command line tool (or whatever kind of tool +the SCM provides to access it). -DamageControl automatically detects new SCM classes in RSCM and generates a default web interface. +==== Special note for non-transactional SCMs +Non-transactional SCMs usually use dates (and not revision identifiers) to report changes. Most SCMs report changes to files +(which will become RSCM::RevisionFile instances) in some sort of log. These changes will typically not be logically +grouped. RSCM::Revisions.add will group revision files that have: +* similar modification time (max 1 minute apart) +* the same commit message +* the same developer + +So when mining for revisions that follow the constraints for revisions.yml, you should also be looking for groupings +in modification time, commit message and developer. + +=== Create files_0.yml +This file should contain the files that will be in the working copy after a checkout of the 1st revision in revisions.yml, +sorted by their path. + +== Implement the methods +Now that we have set up everything needed for the tests, we can run the tests again: + + rake test TEST=test/rscm/scm/mooky_test.rb + +Now you should get errors about methods not being implemented. At this point you should start implementing the methods. + +== Implementation tips +* Run the tests often. Let the error messages guide you in what you do next. +* Use the execute method to invoke command line tools. +* Split the implementation into two classes. One class for parsing logs and one for translating API calls to command line executions. This will allow you to test the log parsing against hard coded logs in your tests. + = 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 @@ -187,8 +197,8 @@ rake gem This will create a gem for RSCM. To install this gem, you have to change to the pkg directory and type - sudo gem install pkg/rscm-0.3.11.gem + sudo gem install pkg/rscm-0.4.X.gem Now you can use RSCM in other Ruby apps with a simple require 'rscm'.