rscm 0.2.1.1404 → 0.3.0

data/README

@@ -1,6 +1,6 @@
-= 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)
@@ -8,15 +8,25 @@ RSCM is to SCM what DBI/JDBC/ODBC are to databases - an SCM-independent API for
 * 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
 
@@ -30,7 +40,7 @@ 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.
@@ -46,29 +56,30 @@ Here is an example of how to use RSCM to get a list of changesets from a CVS rep
   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:
-
-See the DamageControl sources for more detailed examples (DamageControl persists diffs to disk
-and presents them as colourised diffs in its user interface).
+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).
 
 == Future plans
 
@@ -84,7 +95,7 @@ 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
@@ -105,7 +116,7 @@ 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
@@ -162,8 +173,8 @@ You can reuse these classes for other Java based SCMs (if there are any, I don't
 
 == 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.
 
@@ -178,6 +189,6 @@ Now change to the RSCM root directory and type
 
 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'.

data/Rakefile

@@ -4,14 +4,13 @@ require 'rake/testtask'
 require 'rake/rdoctask'
 require 'rake/packagetask'
 require 'rake/gempackagetask'
-require 'rake/contrib/compositepublisher'
 require 'rake/contrib/sshpublisher'
 require 'rake/contrib/rubyforgepublisher'
-require 'lib/rubyforge_file_publisher'
+require 'xforge'
 
 PKG_BUILD     = ENV['PKG_BUILD'] ? '.' + ENV['PKG_BUILD'] : ''
 PKG_NAME      = 'rscm'
-PKG_VERSION   = '0.2.1' + PKG_BUILD
+PKG_VERSION   = '0.3.0' + PKG_BUILD
 PKG_FILE_NAME = "#{PKG_NAME}-#{PKG_VERSION}"
 
 desc "Default Task"
@@ -22,9 +21,11 @@ task :all => [:ant, :gem]
 # To run a specific test: rake test TEST=path/to/test
 fl = FileList.new('test/**/*_test.rb')
 fl.exclude('test/**/mooky*.rb')
-fl.exclude('test/**/monotone*.rb') # Incomplete/unsupported for now - reactivate when more complete!
+#fl.exclude('test/**/monotone*.rb') # Incomplete/unsupported for now - reactivate when more complete!
+fl.exclude('test/**/clearcase*.rb')    # Incomplete/unsupported for now - reactivate when more complete!
 fl.exclude('test/**/darcs*.rb')    # Incomplete/unsupported for now - reactivate when more complete!
-fl.exclude('test/**/perforce*.rb') # Incomplete/unsupported for now - reactivate when more complete!
+#fl.exclude('test/**/perforce*.rb') # Incomplete/unsupported for now - reactivate when more complete!
+#fl.exclude('test/**/p4client*.rb') # Incomplete/unsupported for now - reactivate when more complete!
 fl.exclude('test/**/starteam*.rb') # Too bloody hard to test without a StarTeam server license! Tested ad-hoc.
 Rake::TestTask.new { |t|
   t.libs << "test"
@@ -109,29 +110,23 @@ else
   end
 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
+task :release => [:publish_doc, :publish_files]
+
+task :publish_files => [:gem] do
+  release_files = FileList[
+    "pkg/#{PKG_FILE_NAME}.gem", 
+    "CHANGES"
+  ]
+
+  Rake::XForge::Release.new(PKG_NAME) do |xf|
+    # Never hardcode user name and password in the Rakefile!
+    xf.user_name = ENV['RUBYFORGE_USER']
+    xf.password = ENV['RUBYFORGE_PASSWORD']
+    xf.files = release_files.to_a
+    xf.release_name = "XForge #{PKG_VERSION}"
+  end
+end
 
+task :publish_doc => [:rdoc] do
+  publisher = Rake::RubyForgePublisher.new('rscm', 'aslak_hellesoy')
 end

data/lib/rscm.rb

@@ -1,5 +1,8 @@
-require 'rscm/abstract_scm'
-require 'rscm/changes'
+require 'rscm/annotations'
+require 'rscm/path_converter'
 require 'rscm/logging'
+require 'rscm/better'
+require 'rscm/base'
+require 'rscm/revision'
+require 'rscm/revision_file'
 require 'rscm/time_ext'
-require 'rscm/abstract_scm'

data/lib/rscm/annotations.rb

@@ -1,5 +1,7 @@
 class Class
+
   @@anns = {}
+  @@attr_anns = {}
 
   # Defines annotation(s) for the next defined +attr_reader+ or
   # +attr_accessor+. The +anns+ argument should be a Hash defining annotations
@@ -23,23 +25,24 @@ class Class
   # You may also use annotations to specify more programmatically meaningful metadata. More power to you.
   # 
   def ann(anns)
-    $attr_anns ||= {}
-    $attr_anns.merge!(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]
+    return anns[sym] if(anns && anns[sym])
+    return superclass.method_missing(sym, *args) if superclass
+    return {}
   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
+      @@anns[self][sym] = @@attr_anns.dup if @@attr_anns
     end
-    $attr_anns = nil
+    @@attr_anns = nil
     old_attr_reader(*syms)
   end
 
@@ -48,3 +51,19 @@ class Class
     attr_writer(*syms)
   end
 end
+
+class Object
+  def anns(attr_name)
+    self.class.send(attr_name)
+  end
+
+  def __attr_accessors
+    attrs = []
+    methods.each do |method|
+      if(method =~ /(.*)=/)
+        attrs << "@#{$1}" if methods.index($1) && $1 != "=="
+      end
+    end
+    attrs.sort
+  end
+end

data/lib/rscm/{abstract_scm.rb → base.rb}

@@ -1,44 +1,57 @@
 require 'fileutils'
-require 'rscm/changes'
+require 'rscm/revision'
 require 'rscm/path_converter'
 require 'rscm/annotations'
 
-class String
-  # Turns a String into a Time or an int
-  def to_identifier
-    if(self =~ /20\d\d\d\d\d\d\d\d\d\d\d\d/)
-      # Assume it's a timestamp string - convert to time.
-      Time.parse_ymdHMS(self)
-    else
-      # Assume it's an arbitrary integer.
-      self.to_i
-    end
-  end
-end
-
-class Time
-  def to_s
-    self.ymdHMS
-  end
-end
-
 module RSCM
   # This class defines the RSCM API. The documentation of the various methods
-  # uses CVS' terminology.
+  # uses CVS and Subversion's terminology. (For example, checkout means 'get working copy',
+  # not 'lock for private edit' as in ClearCase or VSS terminology).
+  #
+  # Concrete subclasses of this class provide an API to manage a local working copy
+  # as well as an associated 'central' repository. The main responsibility is working
+  # copy operations:
+  #
+  # * checkout
+  # * revisions
+  # * uptodate?
+  # * checked_out?
+  # * diff
+  # * edit
+  #
+  # In addition to operations related to working copies, the same instance should provide
+  # methods to administer the working copy's associated 'central' repository. These are:
+  #
+  # * central_exists?
+  # * create_central
+  # * can_create_central?
+  # * import_central
+  # * supports_trigger? # TODO: rename to can_install_trigger?
+  # * trigger_installed?
+  # * install_trigger
+  # * uninstall_trigger
+  #
+  # Some methods are a bit fuzzy with respect to their relevance to the working copy or
+  # the associated central repository, as it depends on the nature of the individual underlying 
+  # SCMs. These methods are:
+  #
+  # * label
+  # * name
+  # * transactional?
+  # * checkout_command_line
+  # * update_command_line
   #
   # Some of the methods in this API use +from_identifier+ and +to_identifier+.
   # These identifiers can be either a UTC Time (according to the SCM's clock)
-  # or a String representing a label (according to the SCM's label system).
+  # or a String or Integer representing a label/revision 
+  # (according to the SCM's native label/revision scheme).
   #
-  # If +from_identifier+ or +to_identifier+ are +nil+ they respectively represent
-  # epoch or the infinite future.
+  # If +from_identifier+ or +to_identifier+ are +nil+ they should respectively default to
+  # Time.epoch or Time.infinite.
   #
-  # Most of the methods take a mandatory +checkout_dir+ - even if this may seem
-  # unnecessary. The reason is that some SCMs require a working copy to be checked
-  # out in order to perform certain operations. In order to develop portable code,
-  # you should always pass in a non +nil+ value for +checkout_dir+.
+  # TODO: rename this superclass to 'Base'
   #
-  class AbstractSCM
+  class Base
     include FileUtils
 
     @@classes = []
@@ -51,27 +64,35 @@ module RSCM
 
     # Load all sources under scm, so SCM classes can register themselves
     Dir[File.dirname(__FILE__) + "/scm/*.rb"].each do |src|
-      load(src)
+      require src
     end
 
 
-# TODO: Make changesets yield changesets as they are determined, to avoid
+# TODO: Make revisions yield revisions 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
+# use yielded revisions to do another scm hit - like get diffs. Some SCMs
 # might dead lock on this. Implement a guard for that.
 # TODO: Add some visitor support here too?
 
   public
   
+    attr_accessor :checkout_dir
+  
+    def to_yaml_properties
+      props = instance_variables
+      props.delete("@checkout_dir")
+      props.sort!
+    end
+
     # Whether the physical SCM represented by this instance exists.
     #
-    def exists?
+    def central_exists?
       # The default implementation assumes yes - override if it can be
       # determined programmatically.
       true
     end
     
-    # Whether or not this SCM is transactional.
+    # Whether or not this SCM is transactional (atomic).
     #
     def transactional?
       false
@@ -85,18 +106,29 @@ module RSCM
     # 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
+    def create_central
+      raise "Not implemented"
+    end
+    
+    # Destroysthe central repository. Shuts down any server processes and deletes the repository.
+    # WARNING: calling this may result in loss of data. Only call this if you really want to wipe it out for good!
+    def destroy_central
     end
 
     # Whether a repository can be created.
     #
-    def can_create?
+    def can_create_central?
       false
     end
 
-    # Recursively imports files from a directory
+    # Adds +relative_filename+ to the working copy.
+    def add(relative_filename)
+    end
+
+    # Recursively imports files from a directory into the central scm
     #
-    def import(dir, message)
+    def import_central(dir, message)
+      raise "Not implemented"
     end
 
     # The display name of this SCM
@@ -106,23 +138,19 @@ module RSCM
       self.class.name
     end
 
-    # Gets the label for the working copy currently checked out in +checkout_dir+.
-    #
-    def label(checkout_dir)
-    end
-
     # Open a file for edit - required by scms that checkout files in read-only mode e.g. perforce
     #
     def edit(file)
     end
 
-    # Checks out or updates contents from an SCM to +checkout_dir+ - a local working copy.
+    # Checks out or updates contents from a central 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.
+    # if one doesn't already exist. Then the contents of the central SCM should be pulled into
+    # the working copy.
     #
     # 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
-    # the clock on the SCM machine) or a String - reprsenting a label.
+    # particular time or label. +to_identifier+ should either be a Time (in UTC - according to
+    # the clock on the SCM machine) or a String - reprsenting a label or revision.
     #
     # This method will yield the relative file name of each checked out file, and also return
     # them in an array. Only files, not directories, should be yielded/returned.
@@ -130,13 +158,14 @@ module RSCM
     # This method should be overridden for SCMs that are able to yield checkouts as they happen.
     # 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
+    #
+    def checkout(to_identifier=Time.infinity) # :yield: file
       # the OS doesn't store file timestamps with fractions.
       before_checkout_time = Time.now.utc - 1
 
       # We expect subclasses to implement this as a protected method (unless this whole method is overridden).
-      checkout_silent(checkout_dir, to_identifier)
-      files = Dir["#{checkout_dir}/**/*"]
+      checkout_silent(to_identifier)
+      files = Dir["#{@checkout_dir}/**/*"]
       added = []
       files.each do |file|
         added << file if File.mtime(file).utc > before_checkout_time
@@ -154,45 +183,49 @@ module RSCM
       relative_added_file_paths
     end
   
-    # Returns a ChangeSets object for the period specified by +from_identifier+
-    # and +to_identifier+. See AbstractSCM for details about the parameters.
+    # Returns a Revisions object for the period specified by +from_identifier+ (exclusive, i.e. after)
+    # and +to_identifier+ (inclusive).
     #
-    def changesets(checkout_dir, from_identifier, to_identifier=Time.infinity)
+    def revisions(from_identifier, to_identifier=Time.infinity)
       # Should be overridden by subclasses
-      changesets = ChangeSets.new
-      changesets.add(
-        Change.new(
+      revisions = Revisions.new
+      revisions.add(
+        Revision.new(
           "up/the/chimney",
+          Revision::DELETED,
           "DamageControl",
-          "The #{name} SCM class in #{__FILE__} doesn't\n" +
-            "correctly implement the changesets method. This is\n" +
-            "not a real changeset, but a hint to the developer to go and implement it.\n\n" +
+          "The #{name} class doesn't\n" +
+            "correctly implement the revisions method. This is\n" +
+            "not a real revision, but a hint to the developer to go and implement it.\n\n" +
             "Do It Now!",
           "999",
           Time.now.utc
         )
       )
-      changesets
+      revisions
     end
 
-    # Whether the working copy in +checkout_dir+ is in synch with the central
-    # repository since +from_identifier+.
+    # Whether the working copy is in synch with the central
+    # repository's revision/time identified by +identifier+. 
+    # If +identifier+ is nil, 'HEAD' of repository should be assumed.
     #
-    def uptodate?(checkout_dir, from_identifier)
+    # TODO: rename to in_synch?
+    def uptodate?(identifier)
       # Suboptimal algorithm that works for all SCMs.
-      # Subclasses can override this to increase efficiency.
+      # Subclasses can override this to improve efficiency.
       
-      changesets(checkout_dir, from_identifier).empty?
+      revisions(identifier).empty?
     end
 
     # 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)
-      File.exists?(checkout_dir)
+    def checked_out?
+      File.exists?(@checkout_dir)
     end
 
-    # Whether triggers are supported by this SCM
+    # Whether triggers are supported by this SCM. A trigger is a command that can be executed
+    # upon a completed commit to the SCM.
     def supports_trigger?
       # The default implementation assumes no - override if it can be
       # determined programmatically.
@@ -206,31 +239,36 @@ module RSCM
     # Most implementations will ignore this parameter.
     #
     def install_trigger(trigger_command, install_dir)
+      raise "Not implemented"
     end
 
     # Uninstalls +trigger_command+ from the SCM.
     #
     def uninstall_trigger(trigger_command, install_dir)
+      raise "Not implemented"
     end
 
     # Whether the command denoted by +trigger_command+ is installed in the SCM.
     #
     def trigger_installed?(trigger_command, install_dir)
+      raise "Not implemented"
     end
 
     # The command line to run in order to check out a fresh working copy.
     #
     def checkout_commandline(to_identifier=Time.infinity)
+      raise "Not implemented"
     end
 
     # The command line to run in order to update a working copy.
     #
     def update_commandline(to_identifier=Time.infinity)
+      raise "Not implemented"
     end
 
     # Returns/yields an IO containing the unified diff of the change.
-    def diff(checkout_dir, change, &block)
-      return(yield("Diff not implemented"))
+    def diff(change, &block)
+      return(yield("Not implemented"))
     end
 
     def ==(other_scm)
@@ -243,7 +281,7 @@ module RSCM
 
   protected
 
-    # Takes an array of +absolute_path+s and turn them into an array
+    # Takes an array of +absolute_paths+ and turns it into an array
     # of paths relative to +dir+
     # 
     def to_relative(dir, absolute_paths)