[MERGE] repository write groups

[Martin Pool]

Martin Pool has voted resubmit.
Status is now: Resubmit
Comment:
Since this introduces a new fairly major concept it would be good to add
something to HACKING (before merging, or we'll forget.)  Let me try and
draft it and you can correct it:

   Write groups
   ------------

   Some repositories support the concept of a write_group.

   These are created and returned by ``start_write_group``, and
   concluded by either ``commit_write_group`` or
   ``abort_write_group``.  A write lock must be held on the
   repository for the entire duration.
   At most one write group can be
   active on a repository at a time.

   Write groups are different from write locks in that they explicitly
   control when data is committed into the repository.  Several write
   groups could be committed during a single lock.

   It is guaranteed that if the group is aborted then none of the
   changes will be visible in the repository.  If commit_write_group
   returns, all the data will be permanently visible in the repository.

   The difference between Transactions and write groups is .... that
   transactions are not part of the public api?

If they make promises about transactionality then can knit formats keep
them?

      def test_commit_message(self):
          tree = self.make_branch_and_tree(".")
+        tree.lock_write()
          builder = tree.branch.get_commit_builder([])
          self.record_root(builder, tree)
          builder.finish_inventory()
          rev_id = builder.commit('foo bar blah')
+        tree.unlock()
          rev = tree.branch.repository.get_revision(rev_id)
          self.assertEqual('foo bar blah', rev.message)

The unlock should probably be in a finally in all these tests, even 
though
it's just a test, otherwise we may get open-file errors on Windows.  I
guess we can stand that if it's a failing test, but still.

+        """complete a write group on the decorated repository.

Should have an initial capital (two occurrences.)

+    def start_write_group(self):

Could usefully say 'returns None', since you test for it - a reader 
might
expect it to give back a token or something.  Actually, maybe it should?

> compatability

"compatibility", several times.


For details, see: 
http://bundlebuggy.aaronbentley.com/request/%3C1184806331.11842.41.camel%40localhost.localdomain%3E