+#FORMAT rst
+
+============
+Introduction
+============
+
This directory contains a simple plugin that adds
Subversion (http://subversion.tigris.org/) branch support to
-Bazaar (http://www.bazaar-vcs.org/)
+Bazaar (http://www.bazaar-vcs.org/). This allows ``bzr branch``, ``bzr push``,
+``bzr pull``, and ``bzr co`` to work directly against Subversion repositories.
-You will need a recent version of Bazaar-NG, most likely bzr.dev. If you have
-an older version of Bazaar and don't want to upgrade, try the svn-0.8 branch.
-This contains some hacks to make the Subversion plugin work with Bazaar 0.8.
+The plugin can at the moment be used to commit to, pull from, merge from, push
+to and view logs of Subversion branches from Bazaar.
-You also need the Subversion bindings for python, with my patch for svn_info_t,
-which has been in Subversions' repository since r19413.
+============
+Dependencies
+============
-Simply place this directory in ~/.bazaar/plugins and you should be able
-to check out branches from Subversion using bzr.
+You will need at least version 0.92 of Bazaar or higher.
+
+You also need a fairly recent version of the official Python bindings to the
+Subversion libraries. At the moment, the svn plugin only works with
+Subversion 1.5 (trunk). The python-subversion (not python-svn!) package
+in Ubuntu Feisty and Gutsy and Debian Etch, Lenny and Sid also contain the
+required changes.
+
+If you are running an older version of Python (under 2.5), you will also
+need to have the pysqlite package installed.
+
+In order to be able to use the ``svn-upgrade`` command (for those
+who used earlier versions of bzr-svn), you will need the bzr-rebase
+plugin (http://bazaar-vcs.org/BzrSvn).
+
+========
+Features
+========
+
+The following features are currently present:
+
+- Connecting to remote Subversion repositories over all
+ protocols supported by Subversion itself (at present:
+ svn://, svn+ssh://, http:// (webdav), file://)
+ as well as dump files.
+
+ Checkouts, lightweight checkouts and branching works.
+
+- Track Bazaar merges in Subversion. Merged revisions show up
+ as ghosts.
+
+- Subversion working copies. Can be modified, queried
+ ('bzr status' on a vanilla working copied created with
+ 'svn co' works) and committed from.
+
+- Committing to Subversion from Bazaar.
+
+- Push Bazaar revisions to Subversion.
+
+- Follow branch copies. Revision history is not
+ truncated when a branch was copied in Subversion.
+
+- Efficiently uses network bandwidth.
+
+- Recognizes file metadata (executable bits, symlinks).
+
+- 'svn-import' command with functionality similar to svn2bzr.
+
+- Ability to track merges done with SVK (http://svk.elixus.org/)
+ and write merges.
+
+- Generates consistent file ids and revision ids. Two branches made using
+ this plugin of the same Subversion branch will result in *exactly* the same
+ Bazaar branch.
+
+- Handles complex operations in Subversion: committing to two branches at
+ once, upgrading directories to branches, copies from early revisions, ...
-Jelmer Vernooij <jelmer@samba.org>, April 2006.
+===================
+Future Enhancements
+===================
+
+In the future, I also hope to support:
+
+- Renames. Initial work has been done to support this,
+ but the number of corner cases is wide, so support for this
+ has not been enabled by default yet.
+
+- Better performance. Network-wise (both bandwidth and roundtrips), the plugin
+ is in good shape. However, it is currently quite CPU-intensive for no good
+ reason and I hope to make a couple of improvements in that area.
+
+- Override implementation of get_revision_delta(). Will speed up 'bzr log -v'
+
+- use svn_ra_replay() on systems that have Subversion 1.4. Saves a couple of
+ roundtrips when fetching history.
+
+Some Subversion properties can currently not be represented in Bazaar
+and are therefore ignored for the time being:
+
+- 'svn:ignore' is not imported. There should be a
+ 'Repository.get_ignores(revid)' call in Bazaar rather than a magic
+ '.bzrignore' file.
+
+- 'svn:externals'. Externals should be mapped to Bazaar 'by-reference'
+ nested branches and the other way around. This can't be implemented
+ this until Bazaars nested branch support lands. AaronBentley's work
+ in progress is at http://code.aaronbentley.com/bzr/bzrrepo/nested-trees/.
+ This has been delayed until after 0.9 because of required repository
+ format changes.
+
+- 'svn:mime-type'
+
+- 'svn:eol-style'
+
+- 'svn:keywords'. Requires keywords support in Bazaar. Spec at
+ https://launchpad.net/products/bzr/+spec/bzr-keyword-expansion
+
+Other features currently held back by Bazaars feature set:
+
+- Horizon revision history. Most of the existing Subversion repositories
+ are quite large and it would therefore be nice to be able to limit
+ the amount of history that needs to be retrieved during checkouts.
+
+ Spec at https://launchpad.net/products/bzr/+spec/shallow-checkouts
+
+- Tracking copies.
+
+ Spec at https://launchpad.net/products/bzr/+spec/filecopies
+
+Features held back by Subversion:
+
+- Showing SVN merges as merges in Bazaar. This requires full merge tracking
+ information in Subversion, something which the Subversion folks are working
+ on at the moment (see https://svn.collab.net/repos/svn/branches/merge-tracking).
+
+ Requires tracking cherry-picking support in Bazaar:
+
+ Spec at https://launchpad.net/products/bzr/+spec/bzr-cpick-data
+
+====
+Bugs
+====
+
+Please file bug reports in launchpad. The product URL for bzr-svn is
+https://launchpad.net/products/bzr-svn/. The wiki for this
+plugin is at http://bazaar-vcs.org/BzrSvn.
+
+============
+Installation
+============
+
+Simply place this directory in ~/.bazaar/plugins and you should be able
+to check out branches from Subversion using bzr. Make sure the directory
+name is 'svn'.