Bzr <-> Svn mappings version 4
==============================

.. contents:

Rationale
---------

Mapping version 3 has several problems. 

 * Branching schemes are part of the revision ids; this means that changing 
   the branching scheme changes the identity of the revisions, even if they
   are not directly affected.

 * It relies solely on file properties that can grow very large. Subversion 
   1.5 supports revision properties that can be used for storing bzr-svn-specific 
   metadata as well and are more hidden. They can also be retrieved more easily.

Changes compared to version 3
-----------------------------

Removal of branching schemes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Branching schemes will no longer be part of the revision id, since they 
are irrelevant. All paths will be allowed as valid branch paths.

Optional file properties
~~~~~~~~~~~~~~~~~~~~~~~~
While newer versions (>= 0.4.11) implementing v3 mappings would already set some 
custom revision properties when possible, but not use them, v4 will rely solely 
on revision properties if supported by the server.

Version 4 will always prefer revision properties and use them if available. File 
properties will only be used if the server is running a version of Subversion older 
than 1.5 or if no revision properties have been used yet.

Once revision properties have been used for version 4 in a repository, bzr-svn 
clients will refuse to set file properties. 

Revision properties can, as of svn 1.5, be retrieved very efficiently since 
they can be returned by svn_ra_get_log(). 

Revision properties
-------------------

 * bzr:committer
   Bazaar committer

 * bzr:file-ids
   Map from path to file ids.

 * bzr:mapping-version
   Mapping version ("v4" at the moment)

 * bzr:merge
   Right hand side parent ids.

 * bzr:revision-id
   Revision id of this revision.

 * bzr:revno
   Revision number (distance to NULL_REVISION)

 * bzr:revprop:*
   Bazaar revision property.

 * bzr:root
   Path in the repository to branch root.

 * bzr:gpg-signature
   GPG signature

 * bzr:timestamp
   Timestamp of the commit

 * bzr:log
   Log message (overrides svn:log), optional.

 * bzr:text-parents
   Dictionary of text revision ids if not easily predictable.

 * bzr:required-features
   Comma-separated list of features required to interpret the data 
   set in these revision properties.

 * bzr:base-revision
   Revision id of the left hand side parent - the diff parent.

 * bzr:skip
   If present, this revision will not be checked for a bzr revision.

 * bzr:tags
   Dictionary of tags set in this revision.

Corner cases in mixed environments
==================================
Several scenarios can occur while both v3 and v4 mappings are in use.

 * v3 client commits revision based on v4 mapped revision
   the two clients would each consider this revision to have a different 
   lhs parent.

 * v4 client commits fileprop-based revision based on v3 mapped revision

 * v4 client commits revprop-based revision based on v3 mapped revision, 
   which follows revprop based v4 revisions early in the repo.

 * svn client commits revision based on v3 mapped revision

-> only try to interpret parent metadata with own mapping or older
-> only look for fileprops until the first revprop that appears in revhistory

Upgrade
=======
A new command, svn-set-revprops is provided to set revision properties for 
existing revisions that are already present using file properties.

FIXME: bzr-svn should warn the user to run svn-set-revprops 
if this would help performance.

Mapping 3 revisions will still be retrievable.

Unless otherwise specified, new revisions will be pushed with v4 mappings.



.. vim: ft=rest
