rscm 0.1.0.1338 → 0.2.0

data/README

@@ -1,6 +1,6 @@
-= RSCM - Ruby Source Control Management
+= RSCM - Ruby Source Control Management (0.2.0)
 
-RSCM is to SCM what ODBC/JDBC is to databases - a common API to access 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 a wide variety of 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)
@@ -27,9 +27,10 @@ If you want the latest and greatest, you can get the sources, which live alongsi
 
 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.
@@ -44,7 +45,7 @@ Here is an example of how to use RSCM to get a list of changesets from a CVS rep
 
   require 'rscm'
   
-  scm = RSCM::SVN.new("svn://some.server/some/path/trunk", "trunk")
+  scm = RSCM::Subversion.new("svn://some.server/some/path/trunk", "trunk")
 
   scm.checkout("mycheckout")
   changesets = scm.changesets("mycheckout", Time.utc(2004, 11, 10, 12, 34, 22))
@@ -104,8 +105,8 @@ 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
-- such as with StarTeam - you're probably better off writing the tests from scratch and not
+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
@@ -120,11 +121,11 @@ They're just files).
 
 Let's implement the Mooky class. Take a look at.
 
-  lib/rscm/mooky/mooky.rb
+  lib/rscm/scm/mooky.rb
 
 Try running Mooky's test:
 
-  rake test TEST=test/rscm/mooky/mooky_test.rb
+  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
@@ -151,7 +152,7 @@ should also yield each file name as the execution proceeds).
 Once your checkout command works okay, the test will get you a little further. Just keep
 on going until all tests pass.
 
-NOTE: If the SCM doesn't have a command line utility or a 3rd party Ruby API, but instead
+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.
 
@@ -159,26 +160,10 @@ If the SCM has a Java interface, you can take the same approach as for StarTeam.
 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).
 
-== Writing the web interface (DamageControl only)
-
-If you're contributing a new SCM it would be nice if you took the time to implement a web interface
-that can be used to embed it into DamageControl.
-
-In trunk/damagecontrol, start by creating +app/views/project/_mooky.rhtml+. 
-
-Create a table with 2 columns and a row for each +attr_accessor+ in the Mooky class, preferrably
-with some explanatory text for the users so they know how to fill it in. See how the tooltips
-are used in some of the existing implementations.
-
-You also need a javascript section at the top
-with a function called +mooky_init()+. This will be called when the page is loaded. If you don't
-have plans to do anything fancy here, just leave it blank.
-
-=== Wiring it all up
-
-Just edit +lib/rscm.rb+ and +require+ your new scm class. Now you should see it coming up
-on the Source Control tab in the web interface.
+== Web interface (DamageControl only)
 
+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.
 

data/Rakefile

@@ -11,7 +11,7 @@ require 'lib/rubyforge_file_publisher'
 
 PKG_BUILD     = ENV['PKG_BUILD'] ? '.' + ENV['PKG_BUILD'] : ''
 PKG_NAME      = 'rscm'
-PKG_VERSION   = '0.1.0' + PKG_BUILD
+PKG_VERSION   = '0.2.0' + PKG_BUILD
 PKG_FILE_NAME = "#{PKG_NAME}-#{PKG_VERSION}"
 
 desc "Default Task"
@@ -108,28 +108,29 @@ else
   end
 end
 
-task :publish do
- # publisher = Rake::CompositePublisher.new
-#  publisher.add Rake::RubyForgePublisher.new('rscm', 'aslak_hellesoy')
-
-  RUBYFORGE_GROUP_ID = 490
-  RUBYFORGE_PACKAGE_ID = 552
-  RUBYFORGE_RELEASE_NAME = "rakedrelease"
-
-  Rake::RubyForgeFilePublisher.new(
-    RUBYFORGE_GROUP_ID, 
-    "aslak_hellesoy", 
-    "README",
-    #"pkg/#{PKG_FILE_NAME}.gem", 
-    RUBYFORGE_PACKAGE_ID,
-    RUBYFORGE_RELEASE_NAME
-  ) do |p|
-    p.type_id = 8100
-    p.processor_id = 2000
-    p.preformatted = 1
-    p.release_name = "come on"
-    p.release_changes = "now"
-    p.release_date = Time.utc(2005, 2, 19, 23, 42, 0)
-  end
+task :publish => [:rdoc] do
+  publisher = Rake::CompositePublisher.new
+  publisher.add Rake::RubyForgePublisher.new('rscm', 'aslak_hellesoy')
+  publisher.upload
+
+#  RUBYFORGE_GROUP_ID = 490
+#  RUBYFORGE_PACKAGE_ID = 552
+#  RUBYFORGE_RELEASE_NAME = "rakedrelease"
+#
+#  Rake::RubyForgeFilePublisher.new(
+#    RUBYFORGE_GROUP_ID, 
+#    "aslak_hellesoy", 
+#    "README",
+#    #"pkg/#{PKG_FILE_NAME}.gem", 
+#    RUBYFORGE_PACKAGE_ID,
+#    RUBYFORGE_RELEASE_NAME
+#  ) do |p|
+#    p.type_id = 8100
+#    p.processor_id = 2000
+#    p.preformatted = 1
+#    p.release_name = "come on"
+#    p.release_changes = "now"
+#    p.release_date = Time.utc(2005, 2, 19, 23, 42, 0)
+#  end
 
 end

data/lib/rscm.rb

@@ -2,9 +2,4 @@ require 'rscm/abstract_scm'
 require 'rscm/changes'
 require 'rscm/logging'
 require 'rscm/time_ext'
-# scms
-require 'rscm/mooky/mooky' # for demo purposes only
-require 'rscm/cvs/cvs'
-require 'rscm/darcs/darcs'
-require 'rscm/starteam/starteam'
-require 'rscm/svn/svn'
+require 'rscm/abstract_scm'

data/lib/rscm/abstract_scm.rb

@@ -1,6 +1,7 @@
 require 'fileutils'
 require 'rscm/changes'
 require 'rscm/path_converter'
+require 'rscm/annotations'
 
 class String
   # Turns a String into a Time or an int
@@ -40,6 +41,20 @@ module RSCM
   class AbstractSCM
     include FileUtils
 
+    @@classes = []
+    def self.register(cls) 
+      @@classes << cls unless @@classes.index(cls)
+    end      
+    def self.classes
+      @@classes
+    end
+
+    # Load all sources under scm, so SCM classes can register themselves
+    Dir[File.dirname(__FILE__) + "/scm/*.rb"].each do |src|
+      load(src)
+    end
+
+
 # TODO: Make changesets yield changesets as they are determined, to avoid
 # having to load them all into memory before the method exits. Careful not to
 # use yielded changesets to do another scm hit - like get diffs. Some SCMs
@@ -62,8 +77,13 @@ module RSCM
       false
     end
 
-    # Creates a new repository. Throws an exception if the
-    # repository cannot be created.
+    # Creates a new 'central' repository. This is intended only for creation of 'central'
+    # repositories (not for working copies). You shouldn't have to call this method if a central repository
+    # already exists. This method is used primarily for testing of RSCM, but can also
+    # be used if you *really* want to create a central repository. 
+    # 
+    # This method should throw an exception if the repository cannot be created (for
+    # example if the repository is 'remote' or if it already exists).
     #
     def create
     end
@@ -71,6 +91,7 @@ module RSCM
     # Whether a repository can be created.
     #
     def can_create?
+      false
     end
 
     # Recursively imports files from a directory
@@ -96,6 +117,8 @@ module RSCM
     end
 
     # Checks out or updates contents from an SCM to +checkout_dir+ - a local working copy.
+    # If this is a distributed SCM, this method should create a 'working copy' repository
+    # if one doesn't already exist.
     #
     # The +to_identifier+ parameter may be optionally specified to obtain files up to a
     # particular time or label. +time_label+ should either be a Time (in UTC - according to
@@ -108,13 +131,16 @@ module RSCM
     # For some SCMs this is not possible, or at least very hard. In that case, just override
     # the checkout_silent method instead of this method (should be protected).
     def checkout(checkout_dir, to_identifier=Time.infinity) # :yield: file
-      before = Dir["#{checkout_dir}/**/*"]
+      checkout_time = Time.now
 
       # We expect subclasses to implement this as a protected method (unless this whole method is overridden).
       checkout_silent(checkout_dir, to_identifier)
 
-      after = Dir["#{checkout_dir}/**/*"]
-      added = (after - before)
+      files = Dir["#{checkout_dir}/**/*"]
+      added = []
+      files.each do |file|
+        added << file if File.mtime(file) > checkout_time
+      end
       ignore_paths.each do |regex|
         added.delete_if{|path| path =~ regex}
       end
@@ -123,7 +149,7 @@ module RSCM
       end
       relative_added_file_paths = to_relative(checkout_dir, added_file_paths)
       relative_added_file_paths.each do |path|
-        yield path
+        yield path if block_given?
       end
       relative_added_file_paths
     end
@@ -131,7 +157,7 @@ module RSCM
     # Returns a ChangeSets object for the period specified by +from_identifier+
     # and +to_identifier+. See AbstractSCM for details about the parameters.
     #
-    def changesets(checkout_dir, from_identifier, to_identifier=Time.infinity, files=nil)
+    def changesets(checkout_dir, from_identifier, to_identifier=Time.infinity)
       # Should be overridden by subclasses
       changesets = ChangeSets.new
       changesets.add(
@@ -149,8 +175,8 @@ module RSCM
       changesets
     end
 
-    # Whether the working copy in +checkout_dir+ is uptodate with the repository
-    # since +from_identifier+.
+    # Whether the working copy in +checkout_dir+ is in synch with the central
+    # repository since +from_identifier+.
     #
     def uptodate?(checkout_dir, from_identifier)
       # Suboptimal algorithm that works for all SCMs.
@@ -159,7 +185,7 @@ module RSCM
       changesets(checkout_dir, from_identifier).empty?
     end
 
-    # Whether the project is checked out or not.
+    # Whether the project is checked out from the central repository or not.
     # Subclasses should override this to check for SCM-specific administrative
     # files if appliccable
     def checked_out?(checkout_dir)

data/lib/rscm/annotations.rb

@@ -0,0 +1,50 @@
+class Class
+  @@anns = {}
+
+  # Defines annotation(s) for the next defined +attr_reader+ or
+  # +attr_accessor+. The +anns+ argument should be a Hash defining annotations
+  # for the associated attr. Example:
+  #
+  #   require 'rscm/annotations'
+  #
+  #   class EmailSender
+  #     ann :description => "IP address of the mail server", :tip => "Use 'localhost' if you have a good box, sister!"
+  #     attr_accessor :server
+  #   end
+  #
+  # The EmailSender class' annotations can then be accessed like this:
+  #
+  #   EmailSender.server[:description] # => "IP address of the mail server"
+  #
+  # Yeah right, cool, whatever. What's this good for? It's useful for example if you want to
+  # build some sort of user interface (for example in on Ruby on Rails) that allows editing of
+  # fields, and you want to provide an explanatory text and a tooltip in the UI.
+  #
+  # You may also use annotations to specify more programmatically meaningful metadata. More power to you.
+  # 
+  def ann(anns)
+    $attr_anns ||= {}
+    $attr_anns.merge!(anns)
+  end
+
+  def method_missing(sym, *args) #:nodoc:
+    anns = @@anns[self]
+    return superclass.method_missing(sym, *args) if(anns.nil?)
+    anns[sym]
+  end
+
+  alias old_attr_reader attr_reader #:nodoc:
+  def attr_reader(*syms) #:nodoc:
+    @@anns[self] ||= {}
+    syms.each do |sym|
+      @@anns[self][sym] = $attr_anns.dup if $attr_anns
+    end
+    $attr_anns = nil
+    old_attr_reader(*syms)
+  end
+
+  def attr_accessor(*syms) #:nodoc:
+    attr_reader(*syms)
+    attr_writer(*syms)
+  end
+end

data/lib/rscm/changes.rb

@@ -3,10 +3,7 @@ require 'rscm/time_ext'
 
 module RSCM
 
-  # TODO: add a hook to get committers from a separate class - to support registered pairs
-  # We'll be able to do lots of cool analysis with visitors later -> graphs. mmmmm.
-
-  # A collection of changesets.
+  # A collection of ChangeSet.
   class ChangeSets
     include Enumerable
     include XMLRPC::Marshallable
@@ -220,7 +217,7 @@ module RSCM
     # This is a UTC ruby time
     attr_accessor :time
     
-    def initialize(path=nil, developer=nil, message=nil, revision=nil, time=nil, status=DELETED)
+    def initialize(path=nil, status=nil, developer=nil, message=nil, revision=nil, time=nil)
       @path, @developer, @message, @revision, @time, @status = path, developer, message, revision, time, status
     end
   

data/lib/rscm/logging.rb

@@ -2,4 +2,5 @@ require 'rubygems'
 require_gem 'log4r'
 
 Log = Log4r::Logger.new("rscm")
+Log.level = ENV["LOG4R_LEVEL"] ? ENV["LOG4R_LEVEL"].to_i : 0
 Log.add Log4r::Outputter.stderr

data/lib/rscm/path_converter.rb

@@ -21,10 +21,11 @@ def with_working_dir(dir)
   #
   prev = Dir.pwd
   begin
-    Log.info "Making directory: '#{File.expand_path(dir)}'"
+    dir = File.expand_path(dir)
+    Log.info "Making directory: '#{dir}'"
     FileUtils.mkdir_p(dir)
     Dir.chdir(dir)
-    Log.info "In directory: '#{File.expand_path(dir)}'"
+    Log.info "In directory: '#{dir}'"
     yield
   ensure
     Dir.chdir(prev)

data/lib/rscm/{cvs → scm}/cvs.rb

@@ -1,7 +1,7 @@
 require 'rscm/abstract_scm'
 require 'rscm/path_converter'
 require 'rscm/line_editor'
-require 'rscm/cvs/cvs_log_parser'
+require 'rscm/scm/cvs_log_parser'
 
 module RSCM
 
@@ -10,12 +10,19 @@ module RSCM
   # You need a cvs executable on the PATH in order for it to work.
   #
   # NOTE: On Cygwin this has to be the win32 build of cvs and not the Cygwin one.
-  class CVS < AbstractSCM
+  class Cvs < AbstractSCM
+    register self
 
-  public
+    ann :description => "CVSROOT"
     attr_accessor :root
+
+    ann :description => "module"
     attr_accessor :mod
+
+    ann :description => "Branch"
     attr_accessor :branch
+
+    ann :description => "Password", :tip => "<b>Warning!</b> Password will be shown in cleartext in configuration files."
     attr_accessor :password
     
     def initialize(root=nil, mod=nil, branch=nil, password=nil)
@@ -89,9 +96,9 @@ module RSCM
       files.empty?
     end
 
-    def changesets(checkout_dir, from_identifier, to_identifier=Time.infinity, files=nil)
+    def changesets(checkout_dir, from_identifier, to_identifier=Time.infinity)
       checkout(checkout_dir) unless uptodate?(checkout_dir, nil) # must checkout to get changesets
-      parse_log(checkout_dir, changes_command(from_identifier, to_identifier, files))
+      parse_log(checkout_dir, changes_command(from_identifier, to_identifier))
     end
     
     def diff(checkout_dir, change)
@@ -226,7 +233,7 @@ module RSCM
       changesets = nil
       with_working_dir(checkout_dir) do
         safer_popen(execed_command_line) do |stdout|
-          parser = CVSLogParser.new(stdout)
+          parser = CvsLogParser.new(stdout)
           parser.cvspath = path
           parser.cvsmodule = mod
           changesets = parser.parse_changesets
@@ -235,7 +242,7 @@ module RSCM
       changesets
     end
 
-    def changes_command(from_identifier, to_identifier, files)
+    def changes_command(from_identifier, to_identifier)
       # https://www.cvshome.org/docs/manual/cvs-1.11.17/cvs_16.html#SEC144
       # -N => Suppress the header if no revisions are selected.
       "log #{branch_option} -N #{period_option(from_identifier, to_identifier)}"
@@ -293,11 +300,11 @@ module RSCM
   
     def command_line(cmd, password=nil, simulate=false)
       cvs_options = simulate ? "-n" : ""
-      "cvs \"-d#{root_with_password(password)}\" #{cvs_options} -q #{cmd}"
+      "cvs -f \"-d#{root_with_password(password)}\" #{cvs_options} -q #{cmd}"
     end
 
     def create_root_cvs
-      CVS.new(self.root, "CVSROOT", nil, self.password)
+      Cvs.new(self.root, "CVSROOT", nil, self.password)
     end
 
     def revision_option(identifier)

data/lib/rscm/{cvs → scm}/cvs_log_parser.rb

@@ -5,9 +5,9 @@ require 'ftools'
 
 module RSCM
 
-  class CVSLogParser < AbstractLogParser
-    REVISION_SEPARATOR = /^----------------------------$/
-    ENTRY_SEPARATOR = /^=============================================================================$/
+  class CvsLogParser < AbstractLogParser
+    REVISION_SEPARATOR = /^----------------------------$/ unless defined? REVISION_SEPARATOR
+    ENTRY_SEPARATOR = /^=============================================================================$/ unless defined? ENTRY_SEPARATOR
     
     attr_accessor :cvspath
     attr_accessor :cvsmodule
@@ -154,7 +154,7 @@ module RSCM
     # The state field is "Exp" both for added and modified files. retards!
     # We need some additional logic to figure out whether it is added or not.
     # Maybe look at the revision. (1.1 means new I think. - deal with it later)
-    STATES = {"dead" => Change::DELETED, "Exp" => Change::MODIFIED}
+    STATES = {"dead" => Change::DELETED, "Exp" => Change::MODIFIED} unless defined? STATES
 
   end