diff -r 7ff01befc7ec -r cc33ae50bab3 mercurial/bundle2.py
--- a/mercurial/bundle2.py	Thu May 22 11:14:02 2014 -0700
+++ b/mercurial/bundle2.py	Fri May 23 16:20:30 2014 -0700
@@ -408,7 +408,14 @@
         self._parts.append(part)
 
     def newpart(self, typeid, *args, **kwargs):
-        """create a new part and add it to the containers"""
+        """create a new part and add it to the containers
+
+        As the part is directly added to the containers. For now, this means
+        that any failure to properly initialize the part after calling
+        ``newpart`` should result in a failure of the whole bundling process.
+
+        You can still fall back to manually create and add if you need better
+        control."""
         part = bundlepart(typeid, *args, **kwargs)
         self.addpart(part)
         return part