[Pkg-bazaar-commits] r113 ./bzr-builddeb/people/jdw/merge_upstream: Add some docstrings and TODO comments.

[James Westby]

------------------------------------------------------------
revno: 113
committer: James Westby <jw+debian at jameswestby.net>
branch nick: merge-upstream.siretart
timestamp: Fri 2007-06-22 16:57:39 +0100
message:
  Add some docstrings and TODO comments.
modified:
  merge_upstream.py
-------------- next part --------------
=== modified file 'merge_upstream.py'
--- a/merge_upstream.py	2007-06-22 15:43:18 +0000
+++ b/merge_upstream.py	2007-06-22 15:57:39 +0000
@@ -23,8 +23,32 @@
 
 from bzrlib.plugins.bzrtools.upstream_import import import_tar
 
+# TODO: handle more input sources.
+# TODO: rename/repack tarball in to place.
+# TODO: drop requirement for revision of last upstream, use tags or something
+#       instead.
+# TODO: support using an explicit standalone upstream branch.
+
 def merge_upstream(tree, source, old_revision):
-
+    """Merge a new upstream release.
+
+    A new upstream release will be extracted and imported in to the branch,
+    and then the packaging specific changes merged in to this.
+
+    The revision of the last commit on the upstream "branch", upon which the
+    new upstream will be created. The merge will then be done in to this,
+    and the tree will be left with pending merges, and possibly any conflicts
+    to fix up.
+
+    :param tree: The tree upon which to operate.
+    :type tree: WorkingTree
+    :param source: The filename tarball to import from.
+    :type source: string
+    :param old_revision: The revision of the last commit on the upstream
+                         branch.
+    :type old_revision: RevisionSpec
+    :return: None
+    """
     current_revision = tree.last_revision()
     revno, rev_id = old_revision.in_branch(tree.branch)
     tree.revert([], tree.branch.repository.revision_tree(rev_id))
@@ -34,4 +58,4 @@
     tree.branch.set_last_revision_info(revno, rev_id)
     tree.commit('import upstream from %s' % os.path.basename(source))
     tree.merge_from_branch(tree.branch, to_revision=current_revision)
-    
+