[RFC] Complete Ruby Client Bindings for Subversion 1.3

Right now, the Ruby bindings for the Subversion Client Library are
only 48% implemented (14 out of 29 API functions).

In order to help us finish the Ruby bindings as quickly as possible,
I've mapped out a plan below for completing the Ruby Client Bindings in
time for Subversion 1.3. If you're a user or a developer of
Subversion, I'd love to hear what you think, and if you have any
advice. Thanks!

----------------------------------------------------------------------
A Game Plan
----------------------------------------------------------------------

To find an example of elegant, simple, and high-performance bindings
for Subversion, we don't have to look far. The Subversion Perl
bindings are simple, well-documented, and well-tested. These bindings
are so solid that we've already seen a spanking fast distributed
version-control system built upon them < svk.elixus.org >.

If we're going to build great bindings for Ruby, why re-invent the
wheel? All we need to do is port the Perl bindings to work with Ruby.

We can use the same documentation, the same tests, and very nearly
the same code for the two sets of bindings. It'll be synergy to the
max!

----------------------------------------------------------------------
Summary
----------------------------------------------------------------------

Code:
- 15 new Ruby API functions for the Ruby Client Library:
  * blame, cleanup, export, import, ls, merge, propget, proplist,
    relocate, resolved, revprop_get, revprop_list, status, switch,
    url_from_path

- 4 new Ruby API classes and associated C/SWIG constructors:
  * svn_client_blame_receiver_t, svn_error_t (aka Svn::Error),
    svn_wc_status_t, svn_client_proplist_item_t

- 8 new Ruby API constants:
  * Svn::Core::INVALID_REVNUM, Svn::Error::CLIENT_BAD_REVISION,
    Svn::Error::ENTRY_NOT_FOUND, Svn::Error::FS_NOT_FOUND,
    Svn::Wc::Notify::Action::commit_added,
    Svn::Wc::Notify::Action::commit_postfix_txdelta,
    Svn::Wc::Notify::Action::status_completed,
    Svn::Wc::Notify::Action::status_external
    
Testing:
- 45 new test cases. At least 3 test cases for each of the 15 new Ruby
  API functions.

Documentation:
- All public Ruby API functions and classes will be fully documented using
  comments in the source code.
- This documentation will also be made available in HTML format so
  that Ruby developers can learn how to use the bindings by looking at
  the Subversion web site.

----------------------------------------------------------------------
New API Functions
----------------------------------------------------------------------

To build a list of the needed Ruby API functions, classes, and
constants, I looked at the Perl Client Bindings, and counted
what functions are implemented in Perl but not in Ruby.
  
Deliverables:
- 15 new Ruby API functions for the Ruby Client Library:
  * blame, cleanup, export, import, ls, merge, propget, proplist,
    relocate, resolved, revprop_get, revprop_list, status, switch,
    url_from_path
  * The dependencies for these functions are listed below.
    
----------------------------------------------------------------------
New Dependencies
----------------------------------------------------------------------

To find a list of the dependencies of each of the new API functions,
I looked at the Perl implementations and counted all of the
functions and classes that the Perl bindings use, but the Ruby API
does not have. These are listed below.

Deliverables:
- 4 new Ruby API classes:
  * svn_client_blame_receiver_t:
            implements 'blame' callback
  * svn_error_t:
            allows callbacks to cancel their parent operation
  * svn_wc_status_t:
            implements 'status' callback
  * svn_client_proplist_item_t:
            a class returned from the 'proplist' and 'propget' functions that
describes a property
            
- 6 new C/SWIG functions:
  * svn_swig_rb_blame_func:
            constructor for svn_client_blame_receiver_t
  * svn_swig_rb_cancel_func:
            a constructor for svn_error_t, that allows a callback to cancel a
pending operation
  * svn_swig_rb_status_func:
            constructor for svn_wc_status_t
  * svn_swig_rb_proplist:
            constructor for svn_client_proplist_item_t
  * svn_swig_rb_info:
            constructor for svn_info_t

- 8 new Ruby API constants (used by the new Ruby API functions):
  * Svn::Core::INVALID_REVNUM, Svn::Error::CLIENT_BAD_REVISION,
    Svn::Error::ENTRY_NOT_FOUND, Svn::Error::FS_NOT_FOUND,
    Svn::Wc::Notify::Action::commit_added,
    Svn::Wc::Notify::Action::commit_postfix_txdelta,
    Svn::Wc::Notify::Action::status_completed,
    Svn::Wc::Notify::Action::status_external

----------------------------------------------------------------------
New Documentation
----------------------------------------------------------------------

If we make the Ruby API follow the exact same structure as the Perl
API, it'll be very easy to document the functions -- just port the
Perl documentation to use Ruby syntax!

I've done this. Check out the new documentation at
  http://www.cs.toronto.edu/~james/svn/ruby_docs.html

I did this entire conversion using a few simple regular expressions.
OK, I did a few manual edits, too, but it'd still be quite plausible
to write a script which automatically updates the Ruby documentation
from the originals in Perl.

Deliverables:
- All public Ruby API functions and classes will be fully documented using
  comments in the source code.
- This documentation will also be made available in HTML format so
  that Ruby developers can learn how to use the bindings by looking at
  the Subversion web site.

----------------------------------------------------------------------
New Test Cases
----------------------------------------------------------------------

To be sure that our new API functions work, we'll need probably at
least 3 test cases per new API function. Most of these tests can be
ported directly from Perl. I'll probably write a few regular
expressions to do most of the porting work, and then fix the rest up
by hand. Fortunately, the Perl and Ruby languages are very similar.

In cases where Perl has less than 3 test cases per API function,
we'll need to write a few extra test functions to be sure our
Ruby code works. If these tests are also ported back to Perl,
they can benefit the Perl team too!

Deliverables:
- 45 new test cases. At least 3 test cases for each of the 15 new
  Ruby API functions.

----------------------------------------------------------------------
Usability Demo: Extending SvnShell.rb to support the new functionality
----------------------------------------------------------------------

While making new API functions accessible is great, it's hard to tell
exactly how usable they are until you use them in a real application.
Therefore I propose that we extend the example SvnShell.rb script
to support the full functionality of the new Ruby Client Library.

This demo and experiment will serve to show us how our bindings can
improve. Perhaps both the Ruby and the Perl bindings could benefit
from higher-level wrapper functions to make usage easier? We will find
out.

----------------------------------------------------------------------
Conclusion: Benefits
----------------------------------------------------------------------

Benefits for Ruby Developers:
- High-performance access to Subversion client library using Ruby
- Proven reliability, thanks to the automated test suite
- Easy learning curve, thanks to HTML documentation to be posted on
  the Subversion web site

Benefits for Subversion Developers:
- Increased adoption of Subversion in the Ruby community
- Upgraded Ruby bindings will be easy to maintain because they build
  upon the framework established in the existing SWIG bindings (e.g.
  Ruby, Perl, Python)

----------------------------------------------------------------------
Related Documents
----------------------------------------------------------------------

Extensive documentation on the proposed new functions is available at:
- http://www.cs.toronto.edu/~james/svn/ruby_docs.html#blame

I've also submitted a Summer of Code proposal related to this project.
- http://www.cs.toronto.edu/~james/svn/summer_of_code_proposal.html

-- 
David James -- http://www.cs.toronto.edu/~james
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org